"""

@relation(SDOC-SRS-39, scope=file)

"""

import datetime

import mimetypes

import os

import re

import tempfile

import types

from dataclasses import dataclass, field

from enum import Enum

from pathlib import Path

from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple, Union

import toml

from strictdoc import __version__, environment

from strictdoc.backend.reqif.sdoc_reqif_fields import ReqIFProfile

from strictdoc.backend.sdoc.constants import SDocMarkup

from strictdoc.commands.convert_config import ConvertCommandConfig

from strictdoc.commands.export_config import ExportCommandConfig

from strictdoc.commands.format_config import FormatCommandConfig

from strictdoc.commands.manage_autouid_config import ManageAutoUIDCommandConfig

from strictdoc.commands.manage_new_config import ManageNewCommandConfig

from strictdoc.commands.server_config import ServerCommandConfig

from strictdoc.core.environment import SDocRuntimeEnvironment

from strictdoc.core.feature import Feature

from strictdoc.core.plugin import StrictDocPlugin

from strictdoc.helpers.auto_described import auto_described

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.md5 import get_md5

from strictdoc.helpers.module import import_from_path

from strictdoc.helpers.net import is_valid_host

from strictdoc.helpers.path_filter import validate_mask

if TYPE_CHECKING:

    from strictdoc.core.format import Format

def parse_relation_tuple(column_name: str) -> Optional[Tuple[str, str]]:

    match_result = re.search(

        r"^((Parent|Child|File)?)(\[(.{1,32})])?$", column_name

    )

    if match_result is None:

        return None

    return match_result.group(1), match_result.group(4)

@dataclass

class SourceNodesEntry:

    path: str

    uid: str

    node_type: str

    sdoc_to_source_map: Dict[str, str] = field(default_factory=dict)

    full_path: Optional[Path] = None

class ProjectFeature(str, Enum):

    # Stable features.

    TABLE_SCREEN = "TABLE_SCREEN"

    TRACEABILITY_SCREEN = "TRACEABILITY_SCREEN"

    DEEP_TRACEABILITY_SCREEN = "DEEP_TRACEABILITY_SCREEN"

    MATHJAX = "MATHJAX"

    # Experimental features.

    SEARCH = "SEARCH"

    HTML2PDF = "HTML2PDF"

    REQIF = "REQIF"

    DIFF = "DIFF"

    PROJECT_STATISTICS_SCREEN = "PROJECT_STATISTICS_SCREEN"

    TREE_MAP_SCREEN = "TREE_MAP_SCREEN"

    TRACEABILITY_MATRIX_SCREEN = "TRACEABILITY_MATRIX_SCREEN"

    REQUIREMENT_TO_SOURCE_TRACEABILITY = "REQUIREMENT_TO_SOURCE_TRACEABILITY"

    SOURCE_FILE_LANGUAGE_PARSERS = "SOURCE_FILE_LANGUAGE_PARSERS"

    MERMAID = "MERMAID"

    NESTOR = "NESTOR"

    ALL_FEATURES = "ALL_FEATURES"

    @staticmethod

    def all() -> List[str]:  # noqa: A003

        return list(map(lambda c: c.value, ProjectFeature))

class ProjectConfigDefault:

    DEFAULT_PROJECT_TITLE = "Untitled Project"

    DEFAULT_DIR_FOR_SDOC_ASSETS = "_static"

    DEFAULT_DIR_FOR_OUTPUT = "output"

    DEFAULT_DIR_FOR_SDOC_CACHE = "output/_cache"

    DEFAULT_FEATURES: List[str] = [

        ProjectFeature.TABLE_SCREEN,

        ProjectFeature.TRACEABILITY_SCREEN,

        ProjectFeature.DEEP_TRACEABILITY_SCREEN,

        ProjectFeature.SEARCH,

    ]

    DEFAULT_SERVER_HOST = "127.0.0.1"

    DEFAULT_SERVER_PORT = 5111

    DEFAULT_BUNDLE_DOCUMENT_VERSION = "@GIT_VERSION (Git branch: @GIT_BRANCH)"

    DEFAULT_BUNDLE_DOCUMENT_COMMIT_DATE = "@GIT_COMMIT_DATETIME"

    DEFAULT_SECTION_BEHAVIOR = "[SECTION]"

def resolve_favicon_variant(

    environment: SDocRuntimeEnvironment, is_running_on_server: bool

) -> str:

    """Resolve which favicon.svg.jinja variant identifies this process."""

    if environment.is_test_env:

        return "test"

    if environment.is_development_mode:

        return "dev"

    if not is_running_on_server:

        return "export"

    return "default"

@auto_described

class ProjectConfig:

    """

    @relation(SDOC-SRS-119, scope=class)

    """

    def __init__(

        self,

        *,

        project_title: str = ProjectConfigDefault.DEFAULT_PROJECT_TITLE,

        dir_for_sdoc_assets: str = ProjectConfigDefault.DEFAULT_DIR_FOR_SDOC_ASSETS,

        dir_for_sdoc_cache: str = ProjectConfigDefault.DEFAULT_DIR_FOR_SDOC_CACHE,

        project_features: Optional[List[Union[str, Feature]]] = None,

        server_host: str = ProjectConfigDefault.DEFAULT_SERVER_HOST,

        server_port: int = ProjectConfigDefault.DEFAULT_SERVER_PORT,

        input_paths: Optional[List[str]] = None,

        include_doc_paths: Optional[List[str]] = None,

        exclude_doc_paths: Optional[List[str]] = None,

        source_root_path: Optional[str] = None,

        include_source_paths: Optional[List[str]] = None,

        exclude_source_paths: Optional[List[str]] = None,

        grammars: Optional[Dict[str, str]] = None,

        test_report_root_dict: Optional[Dict[str, str]] = None,

        source_nodes: Optional[List[SourceNodesEntry]] = None,

        html2pdf_strict: bool = False,

        html2pdf_template: Optional[str] = None,

        html2pdf_forced_page_break_nodes: Optional[List[str]] = None,

        bundle_document_uid: Optional[str] = None,

        bundle_document_version: Optional[

            str

        ] = ProjectConfigDefault.DEFAULT_BUNDLE_DOCUMENT_VERSION,

        bundle_document_date: Optional[

            str

        ] = ProjectConfigDefault.DEFAULT_BUNDLE_DOCUMENT_COMMIT_DATE,

        traceability_matrix_relation_columns: Optional[

            List[Tuple[str, Optional[str]]]

        ] = None,

        reqif_profile: str = ReqIFProfile.P01_SDOC,

        # FIXME: Change to true by default.

        reqif_multiline_is_xhtml: bool = False,

        # FIXME: Change to true by default.

        reqif_enable_mid: bool = False,

        reqif_import_markup: Optional[str] = None,

        diff_git_revisions: Optional[str] = None,

        diff_dir_revisions: Optional[Tuple[str, str]] = None,

        chromedriver: Optional[str] = None,

        # FIXME: The section_behavior field will be removed by the end of 2025-Q4.

        section_behavior: Optional[

            str

        ] = ProjectConfigDefault.DEFAULT_SECTION_BEHAVIOR,

        statistics_generator: Optional[str] = None,

        document_line_width: Optional[int] = None,

        # Logo path can be set in the project config to customize the launcher's appearance for a specific project.

        launcher_logo_path: Optional[str] = None,

        # Favicon path can be set in the project config to customize the

        # browser-tab favicon for a project's own (non-dev, non-test) server

        # or static export. Ignored for the dev/test favicon variants.

        favicon_path: Optional[str] = None,

        # Custom CSS path can be set in the project config to extend or

        # override StrictDoc's default stylesheets in the HTML export and

        # on the server.

        custom_css_path: Optional[str] = None,

        user_plugin: Optional[StrictDocPlugin] = None,

        formats: Optional[List["Format"]] = None,

        # Reserved for StrictDoc's internal use.

        _config_last_update: Optional[datetime.datetime] = None,

    ) -> None:

        self.environment: SDocRuntimeEnvironment = environment

        # Settings obtained from the strictdoc.toml config file.

        self.project_title: str = project_title

        self.dir_for_sdoc_assets: str = dir_for_sdoc_assets

        if env_cache_dir := os.environ.get("STRICTDOC_CACHE_DIR"):

            # The only use case for STRICTDOC_CACHE_DIR is to make the cache

            # local to an itest folder.

            assert env_cache_dir == "Output/_cache", env_cache_dir

            dir_for_sdoc_cache = env_cache_dir

        elif dir_for_sdoc_cache == "$TMPDIR":

            dir_for_sdoc_cache = os.path.join(

                tempfile.gettempdir(),

                "strictdoc_cache",

                get_md5(os.getcwd()),

            )

        # Adding a __version__ part to the cache directory improves traceability

        # by indicating which StrictDoc version the cache belongs to.

        # This helps prevent issues when switching between versions that may use

        # incompatible cache schemas.

        dir_for_sdoc_cache = os.path.join(dir_for_sdoc_cache, __version__)

        self.dir_for_sdoc_cache: str = dir_for_sdoc_cache

        #

        # project_features

        #

        project_features_: List[Union[str, Feature]] = (

            project_features

            if project_features is not None

            else list(ProjectConfigDefault.DEFAULT_FEATURES)

        )

        assert isinstance(project_features_, list), (

            f"config: project_features: parameter must be an "

            f"array: '{project_features_}'."

        )

        for feature in project_features_:

            if isinstance(feature, Feature):

                continue

            assert feature in ProjectFeature.all(), (

                f"config: project_features: unknown feature declared: "

                f"'{feature}'."

            )

        if ProjectFeature.ALL_FEATURES in project_features_:

            custom_features = [

                feature

                for feature in project_features_

                if isinstance(feature, Feature)

            ]

            project_features_ = [*ProjectFeature.all(), *custom_features]

        self.project_features: List[Union[str, Feature]] = project_features_

        #

        # server_host and server_port

        #

        assert is_valid_host(server_host), (

            f"config: server_host: invalid host: {server_host}'."

        )

        self.server_host: str = server_host

        assert isinstance(server_port, int) and 1024 < server_port < 65000, (

            f"strictdoc.toml: 'port': invalid port: {server_port}'."

        )

        self.server_port: int = server_port

        #

        # input_paths

        #

        self.input_paths: Optional[List[str]] = input_paths

        #

        # include_doc_paths

        #

        include_doc_paths = include_doc_paths or []

        assert isinstance(include_doc_paths, list), include_doc_paths

        for include_doc_path in include_doc_paths:

            try:

                validate_mask(include_doc_path)

            except SyntaxError as exception_:

                raise ValueError(

                    f"config: include_doc_paths: {exception_}"

                ) from exception_

        self.include_doc_paths: List[str] = include_doc_paths

        #

        # exclude_doc_paths

        #

        exclude_doc_paths = exclude_doc_paths or []

        assert isinstance(exclude_doc_paths, list), exclude_doc_paths

        for exclude_doc_path in exclude_doc_paths:

            try:

                validate_mask(exclude_doc_path)

            except SyntaxError as exception_:

                raise ValueError(

                    f"config: exclude_doc_paths: {exception_}"

                ) from exception_

        self.exclude_doc_paths: List[str] = exclude_doc_paths

        #

        # include_source_paths

        #

        include_source_paths = include_source_paths or []

        assert isinstance(include_source_paths, list), include_source_paths

        for include_source_path in include_source_paths:

            try:

                validate_mask(include_source_path)

            except SyntaxError as exception_:

                raise ValueError(

                    f"config: include_source_paths: {exception_}"

                ) from exception_

        self.include_source_paths: List[str] = include_source_paths

        #

        # exclude_source_paths

        #

        exclude_source_paths = exclude_source_paths or []

        assert isinstance(exclude_source_paths, list), exclude_source_paths

        for exclude_source_path in exclude_source_paths:

            try:

                validate_mask(exclude_source_path)

            except SyntaxError as exception_:

                raise ValueError(

                    f"config: exclude_source_paths: {exception_}"

                ) from exception_

        self.exclude_source_paths: List[str] = exclude_source_paths

        #

        # source_root_path

        #

        self.source_root_path: Optional[str] = source_root_path

        #

        # grammars - Grammar aliases.

        #

        self.grammars: Dict[str, str] = grammars or {}

        self.test_report_root_dict: Dict[str, str] = (

            test_report_root_dict if test_report_root_dict is not None else {}

        )

        self.source_nodes: List[SourceNodesEntry] = (

            source_nodes if source_nodes is not None else []

        )

        # Settings derived from the command-line parameters.

        # Common settings.

        self.output_dir: str = ProjectConfigDefault.DEFAULT_DIR_FOR_OUTPUT

        # Export action.

        self.export_output_html_root: str = os.path.join(

            self.output_dir, "html"

        )

        self.export_formats: Optional[List[str]] = None

        self.formats: List[Format] = (

            formats if formats is not None else ProjectConfig.default_formats()

        )

        self.export_included_documents: bool = False

        self.generate_bundle_document: bool = False

        self.filter_nodes: Optional[str] = None

        self.excel_export_fields: Optional[List[str]] = None

        assert isinstance(html2pdf_strict, bool), (

            "config: html2pdf_strict: "

            f"must be a True/False value: {html2pdf_strict}."

        )

        self.html2pdf_strict: bool = html2pdf_strict

        self.html2pdf_template: Optional[str] = html2pdf_template

        if html2pdf_forced_page_break_nodes is not None:

            assert isinstance(html2pdf_forced_page_break_nodes, list)

            assert len(html2pdf_forced_page_break_nodes) <= 10

        self.html2pdf_forced_page_break_nodes: List[str] = (

            html2pdf_forced_page_break_nodes or []

        )

        self.bundle_document_uid: Optional[str] = bundle_document_uid

        self.bundle_document_version: Optional[str] = bundle_document_version

        self.bundle_document_date: Optional[str] = bundle_document_date

        self.traceability_matrix_relation_columns: Optional[

            List[Tuple[str, Optional[str]]]

        ] = traceability_matrix_relation_columns

        #

        # ReqIF

        #

        self.reqif_profile: str = reqif_profile

        assert isinstance(reqif_multiline_is_xhtml, bool), (

            reqif_multiline_is_xhtml

        )

        self.reqif_multiline_is_xhtml: bool = reqif_multiline_is_xhtml

        assert isinstance(reqif_enable_mid, bool), reqif_enable_mid

        self.reqif_enable_mid: bool = reqif_enable_mid

        if reqif_import_markup is not None:

            assert reqif_import_markup in SDocMarkup.ALL, (

                "config: reqif_import_markup: expected a valid markup: "

                f"({SDocMarkup.ALL}). Got: "

                f"'{reqif_import_markup}'."

            )

        self.reqif_import_markup: Optional[str] = reqif_import_markup

        #

        # auto_uid_mode: default is False. The True-case is used by the

        # manage/auto_uid command: the SDocNodeValidator will

        # not raise an exception if it sees a node with a missing UID.

        # Important for a special case:

        # The Manage UID command auto-generates the UID, so the field presence

        # validation has to be relaxed.

        # The GitHub issue report:

        # manage auto-uid: UID field REQUIRED True leads to an error

        # https://github.com/strictdoc-project/strictdoc/issues/1896

        #

        self.auto_uid_mode = False

        self.autouuid_include_sections: bool = False

        self.view: Optional[str] = None

        self.diff_git_revisions: Optional[str] = diff_git_revisions

        self.diff_dir_revisions: Optional[Tuple[str, str]] = diff_dir_revisions

        self.chromedriver: Optional[str] = chromedriver

        self.section_behavior: Optional[str] = section_behavior

        self.statistics_generator: Optional[str] = statistics_generator

        if document_line_width is not None:

            assert isinstance(document_line_width, int), document_line_width

            assert document_line_width >= 80, (

                f"config: document_line_width: minimum acceptable value is 80, "

                f"got: {document_line_width}."

            )

        self.document_line_width: Optional[int] = document_line_width

        self.user_plugin: Optional[StrictDocPlugin] = user_plugin

        # Optional launcher logo path (absolute or workspace-relative).

        self.launcher_logo_path: Optional[str] = launcher_logo_path

        # Optional custom favicon path, project-relative. Validated and

        # resolved to an absolute path in validate_and_finalize().

        self.favicon_path: Optional[str] = favicon_path

        # Optional custom CSS path, project-relative. Validated and

        # resolved to an absolute path in validate_and_finalize().

        self.custom_css_path: Optional[str] = custom_css_path

        self.config_last_update: Optional[datetime.datetime] = (

            _config_last_update

        )

        self.is_running_on_server: bool = False

        self.watch_enabled: bool = False

    @staticmethod

    def default_config() -> "ProjectConfig":

        return ProjectConfig()

    @staticmethod

    def default_formats() -> List["Format"]:

        # Imported locally to avoid a circular import: each Format module

        # imports generator/writer classes that, transitively, import

        # ProjectConfig itself.

        from strictdoc.backend.excel.export.excel_format import (  # noqa: PLC0415

            ExcelFormat,

        )

        from strictdoc.backend.gcov.gcov_format import (  # noqa: PLC0415

            GCovJSONFormat,

        )

        from strictdoc.backend.json.json_format import (  # noqa: PLC0415

            JSONFormat,

        )

        from strictdoc.backend.markdown.markdown_format import (  # noqa: PLC0415

            MarkdownFormat,

        )

        from strictdoc.backend.reqif.reqif_format import (  # noqa: PLC0415

            ReqIFFormat,

        )

        from strictdoc.backend.rst.rst_format import (  # noqa: PLC0415

            RSTFormat,

        )

        from strictdoc.backend.sdoc.sdoc_format import (  # noqa: PLC0415

            SDocFormat,

        )

        from strictdoc.backend.sdoc_source_code.test_reports.junit_xml_format import (  # noqa: PLC0415

            JUnitXMLFormat,

        )

        from strictdoc.backend.sdoc_source_code.test_reports.robot_xml_format import (  # noqa: PLC0415

            RobotXMLFormat,

        )

        from strictdoc.backend.spdx.spdx_format import (  # noqa: PLC0415

            SPDXFormat,

        )

        from strictdoc.export.html.html_format import (  # noqa: PLC0415

            HTMLFormat,

        )

        from strictdoc.features.doxygen.doxygen_format import (  # noqa: PLC0415

            DoxygenFormat,

        )

        from strictdoc.features.html2pdf.html2pdf_format import (  # noqa: PLC0415

            HTML2PDFFormat,

        )

        return [

            HTMLFormat(),

            HTML2PDFFormat(),

            RSTFormat(),

            ExcelFormat(),

            ReqIFFormat(),

            SDocFormat(),

            MarkdownFormat(),

            DoxygenFormat(),

            SPDXFormat(),

            JUnitXMLFormat(),

            GCovJSONFormat(),

            RobotXMLFormat(),

            JSONFormat(),

        ]

    @staticmethod

    def _builtin_features_by_handle() -> Dict[str, Feature]:

        # Imported locally to avoid a circular import, mirroring

        # default_formats() above.

        from strictdoc.features.project_statistics.feature import (  # noqa: PLC0415

            ProjectStatisticsFeature,

        )

        return {

            feature.HANDLE: feature for feature in [ProjectStatisticsFeature()]

        }

    def get_features(self) -> List[Feature]:

        """

        Resolve self.project_features (a mix of built-in string handles and

        directly-registered Feature instances) into concrete Feature

        instances. A string handle that isn't backed by a built-in Feature

        yet (i.e. most ProjectFeature enum members, which have not been

        migrated to the Feature abstraction) resolves to nothing here.

        """

        builtin_features_by_handle = ProjectConfig._builtin_features_by_handle()

        resolved_features: List[Feature] = []

        for feature in self.project_features:

            if isinstance(feature, Feature):

                resolved_features.append(feature)

            elif feature in builtin_features_by_handle:

                resolved_features.append(builtin_features_by_handle[feature])

        return resolved_features

    def get_feature(self, handle: str) -> Optional[Feature]:

        for feature in self.get_features():

            if feature.HANDLE == handle:

                return feature

        return None

    def get_editable_document_extensions(self) -> List[str]:

        """

        File extensions a new/edited document may use, i.e. the union of

        supported_extensions() from every format in self.formats that

        supports_edit(). Computed live from self.formats so that adding or

        removing a format changes the accepted extensions without any

        further code changes.

        """

        extensions: List[str] = []

        for format_ in self.formats:

            if not format_.supports_edit():

                continue

            for extension in format_.supported_extensions():

                if extension not in extensions:

                    extensions.append(extension)

        return extensions

    # Some server command settings can override the project config settings.

    def integrate_server_config(

        self, server_config: ServerCommandConfig

    ) -> None:

        self.is_running_on_server = True

        self.watch_enabled = server_config.watch

        if (server_host_ := server_config.host) is not None:

            self.server_host = server_host_

        if (server_port_ := server_config.port) is not None:

            self.server_port = server_port_

        self.input_paths = [server_config.get_full_input_path()]

        if self.source_root_path is None:

            source_root_path = self.input_paths[0]

            # If the input argument is a relative path, convert it to an

            # absolute path.

            source_root_path = os.path.abspath(source_root_path)

            source_root_path = source_root_path.rstrip("/")

            self.source_root_path = source_root_path

        # When setting the output dir, the CLI argument takes precedence.

        output_dir = self.output_dir

        if server_config.output_path is not None:

            output_dir = server_config.output_path

        elif output_dir == ProjectConfigDefault.DEFAULT_DIR_FOR_OUTPUT:

            output_dir = "./output/server"

        self.output_dir = output_dir

        self.export_output_html_root = os.path.join(output_dir, "html")

        # If a custom cache folder is not specified in the config, adjust the

        # cache folder to be located in the output folder.

        if self.dir_for_sdoc_cache.startswith(

            ProjectConfigDefault.DEFAULT_DIR_FOR_SDOC_CACHE

        ):

            self.dir_for_sdoc_cache = os.path.join(

                output_dir, "_cache", __version__

            )

        self.export_formats = ["html"]

        self.generate_bundle_document = False

        self.export_included_documents = True

    def integrate_export_config(

        self, export_config: ExportCommandConfig

    ) -> None:

        if export_config.project_title is not None:

            self.project_title = export_config.project_title

        self.input_paths = export_config.input_paths

        if self.source_root_path is None:

            source_root_path = export_config.input_paths[0]

            # If the input argument is a relative path, convert it to an

            # absolute path.

            source_root_path = os.path.abspath(source_root_path)

            source_root_path = source_root_path.rstrip("/")

            self.source_root_path = source_root_path

        #

        # Adjust the default output dir to the user-provided dir if needed.

        #

        output_dir = self.output_dir

        if export_config.output_dir is not None:

            output_dir = export_config.output_dir

        if not os.path.isabs(output_dir):

            cwd = os.getcwd()

            output_dir = os.path.join(cwd, output_dir)

        self.output_dir = output_dir

        # If a custom cache folder is not specified in the config, adjust the

        # cache folder to be located in the output folder.

        if self.dir_for_sdoc_cache.startswith(

            ProjectConfigDefault.DEFAULT_DIR_FOR_SDOC_CACHE

        ):

            self.dir_for_sdoc_cache = os.path.join(

                output_dir, "_cache", __version__

            )

        self.export_output_html_root = os.path.join(self.output_dir, "html")

        self.export_formats = export_config.formats

        self.export_included_documents = export_config.included_documents

        self.generate_bundle_document = export_config.generate_bundle_document

        self.filter_nodes = export_config.filter_nodes

        self.excel_export_fields = export_config.fields

        self.view = export_config.view

        if ProjectFeature.DIFF in self.project_features:

            if export_config.generate_diff_git is not None:

                self.diff_git_revisions = export_config.generate_diff_git

            if export_config.generate_diff_dirs is not None:

                self.diff_dir_revisions = export_config.generate_diff_dirs

        self.chromedriver = export_config.chromedriver

        if (

            export_config.enable_mathjax

            and ProjectFeature.MATHJAX not in self.project_features

        ):

            self.project_features.append(ProjectFeature.MATHJAX)

        if export_config.reqif_profile is not None:

            self.reqif_profile = export_config.reqif_profile

        # If the TOML file sets this to True, ignore what is in CLI.

        if not self.reqif_multiline_is_xhtml:

            self.reqif_multiline_is_xhtml = (

                export_config.reqif_multiline_is_xhtml

            )

        if not self.reqif_enable_mid:

            self.reqif_enable_mid = export_config.reqif_enable_mid

    def validate_and_finalize(self) -> None:

        project_path = self.get_project_root_path()

        #

        # Validate source nodes config.

        #

        if (

            len(self.source_nodes) > 0

            and ProjectFeature.REQUIREMENT_TO_SOURCE_TRACEABILITY

            not in self.project_features

        ):

            print(  # noqa: T201

                "warning: defining source_nodes without enabling REQUIREMENT_TO_SOURCE_TRACEABILITY "

                "has no effect"

            )

        if ProjectFeature.SOURCE_FILE_LANGUAGE_PARSERS in self.project_features:

            print(  # noqa: T201

                "info: the SOURCE_FILE_LANGUAGE_PARSERS feature is no longer "

                "experimental and is now enabled by default. "

                "It can be safely removed from the project configuration."

            )

        if ProjectFeature.MATHJAX in self.project_features:

            DEPRECATION_ENGINE.add_message(

                "MATHJAX_feature_deprecated",

                "The MATHJAX feature is now enabled by default and no longer "

                "needs to be listed in the project configuration. "

                "Please remove it from the project_features list in your "

                "strictdoc_config.py file.",

            )

        if ProjectFeature.MERMAID in self.project_features:

            DEPRECATION_ENGINE.add_message(

                "MERMAID_feature_deprecated",

                "The MERMAID feature is now enabled by default and no longer "

                "needs to be listed in the project configuration. "

                "Please remove it from the project_features list in your "

                "strictdoc_config.py file.",

            )

        #

        # Validate HTML2PDF template path.

        #

        if (html2pdf_template := self.html2pdf_template) is not None:

            assert not os.path.isabs(html2pdf_template)

            if project_path is not None:

                html2pdf_template = os.path.join(

                    project_path, html2pdf_template

                )

            if not os.path.isfile(html2pdf_template):

                raise ValueError(

                    "config: html2pdf_template: "

                    f"invalid path to a template file: {html2pdf_template}."

                )

        #

        # Validate favicon path.

        #

        if (favicon_path := self.favicon_path) is not None:

            assert not os.path.isabs(favicon_path)

            if project_path is not None:

                favicon_path = os.path.join(project_path, favicon_path)

            if not os.path.isfile(favicon_path):

                raise ValueError(

                    "config: favicon_path: "

                    f"invalid path to a favicon file: {favicon_path}."

                )

            self.favicon_path = favicon_path

        #

        # Validate custom CSS path.

        #

        if (custom_css_path := self.custom_css_path) is not None:

            assert not os.path.isabs(custom_css_path)

            if project_path is not None:

                custom_css_path = os.path.join(project_path, custom_css_path)

            if not os.path.isfile(custom_css_path):

                raise ValueError(

                    "config: custom_css_path: "

                    f"invalid path to a CSS file: {custom_css_path}."

                )

            self.custom_css_path = custom_css_path

        #

        # Validate path to Chrome Driver.

        #

        if (

            chromedriver := self.chromedriver

        ) is not None and not os.path.isfile(chromedriver):

            raise ValueError(

                f"config: chromedriver: not found at path: {chromedriver}."

            )

        #

        # Resolve the source root path.

        #

        if os.path.isdir(project_path):

            source_root_path = self.source_root_path

            if source_root_path is not None:

                original_source_root_path = source_root_path

                if not os.path.isabs(source_root_path):

                    source_root_path = os.path.join(

                        project_path, source_root_path

                    )

                    source_root_path = os.path.abspath(source_root_path)

                if not os.path.isdir(source_root_path):

                    raise ValueError(

                        "config: "

                        "source_root_path: "

                        f"Provided path does not exist: "

                        f"{original_source_root_path}."

                    )

                self.source_root_path = source_root_path

        #

        # Read exclude paths from .gitignore. Add them to the user project's

        # both SDoc and source file search paths.

        #

        path_to_gitignore = os.path.join(project_path, ".gitignore")

        if os.path.isfile(path_to_gitignore):

            patterns = ["/.git/"]

            with open(path_to_gitignore, encoding="utf-8") as f:

                for line_ in f:

                    line = line_.strip()

                    if not line or line.startswith("#"):

                        continue

                    # Ignore !-negated gitignores for now or reimplement

                    # using a dedicated gitignore Python library.

                    if line.startswith("!"):

                        continue

                    patterns.append(line)

            self.exclude_doc_paths.extend(patterns)

            self.exclude_source_paths.extend(patterns)

        #

        # Validate that the provided grammar shortcuts all point to existing

        # grammar files.

        #

        for grammar_alias_, grammar_path_ in list(self.grammars.items()):

            assert grammar_alias_.startswith("@"), (

                "Grammar alias must start with an '@' character."

            )

            assert "." not in grammar_alias_, (

                "Grammar alias must not contain any . characters."

            )

            assert os.path.isfile(os.path.join(project_path, grammar_path_)), (

                "Grammar path must point to an existing path relative to the "

                f"project config file: {grammar_path_}."

            )

            if grammar_path_.startswith("./"):

                self.grammars[grammar_alias_] = grammar_path_.removeprefix("./")

    def is_feature_activated(self, feature: ProjectFeature) -> bool:

        return feature in self.project_features

    def get_favicon_variant(self) -> str:

        return resolve_favicon_variant(

            self.environment, self.is_running_on_server

        )

    def get_custom_favicon_path(self) -> Optional[str]:

        if self.favicon_path is None:

            return None