strictdoc 0.0.42a2__tar.gz → 0.0.42a5__tar.gz

{strictdoc-0.0.42a2 → strictdoc-0.0.42a5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: strictdoc
-Version: 0.0.42a2
+Version: 0.0.42a5
 Summary: StrictDoc is open-source software for technical documentation and requirements management.
 Project-URL: Changelog, https://github.com/strictdoc-project/strictdoc/blob/main/CHANGELOG.md
 Project-URL: Homepage, https://strictdoc.readthedocs.io/en/stable/

{strictdoc-0.0.42a2 → strictdoc-0.0.42a5}/requirements.check.txt

@@ -9,6 +9,8 @@ ruff
 
 # Unit tests
 pytest>=6.2.2
+# Pytest fixture that provides fake file system for testing code that accesses
+# file systems.
 pyfakefs>=4.5.5
 coverage>=5.4
 # httpx is needed for running server-related unit tests.

{strictdoc-0.0.42a2 → strictdoc-0.0.42a5}/strictdoc/__init__.py

@@ -1,6 +1,6 @@
 from strictdoc.core.environment import SDocRuntimeEnvironment
 
-__version__ = "0.0.42a2"
+__version__ = "0.0.42a5"
 
 
 environment = SDocRuntimeEnvironment(__file__)

{strictdoc-0.0.42a2 → strictdoc-0.0.42a5}/strictdoc/core/document_finder.py

@@ -11,6 +11,7 @@ from strictdoc.core.file_tree import (
     FileTree,
     PathFinder,
 )
+from strictdoc.core.project_config import ProjectConfig
 from strictdoc.helpers.textx import drop_textx_meta
 from strictdoc.helpers.timing import measure_performance, timing_decorator
 
@@ -18,7 +19,9 @@ from strictdoc.helpers.timing import measure_performance, timing_decorator
 class DocumentFinder:
     @staticmethod
     @timing_decorator("Find and read SDoc files")
-    def find_sdoc_content(config: ExportCommandConfig, parallelizer):
+    def find_sdoc_content(
+        config: ExportCommandConfig, project_config: ProjectConfig, parallelizer
+    ):
         for paths_to_files_or_doc in config.input_paths:
             if not os.path.exists(paths_to_files_or_doc):
                 sys.stdout.flush()
@@ -30,7 +33,9 @@ class DocumentFinder:
                 print(err)  # noqa: T201
                 sys.exit(1)
 
-        file_tree, asset_dirs = DocumentFinder._build_file_tree(config)
+        file_tree, asset_dirs = DocumentFinder._build_file_tree(
+            config, project_config=project_config
+        )
         document_tree = DocumentFinder._build_document_tree(
             file_tree, config.output_html_root, parallelizer
         )
@@ -118,7 +123,9 @@ class DocumentFinder:
         )
 
     @staticmethod
-    def _build_file_tree(config: ExportCommandConfig):
+    def _build_file_tree(
+        config: ExportCommandConfig, project_config: ProjectConfig
+    ):
         asset_dirs = []
         root_trees = []
 
@@ -171,6 +178,8 @@ class DocumentFinder:
                 root_path=path_to_doc_root,
                 ignored_dirs=[config.output_dir],
                 extensions=[".sdoc"],
+                include_paths=project_config.include_doc_paths,
+                exclude_paths=project_config.exclude_doc_paths,
             )
             root_trees.append(file_tree_structure)
 

{strictdoc-0.0.42a2 → strictdoc-0.0.42a5}/strictdoc/core/file_tree.py

@@ -1,7 +1,9 @@
 import collections
+import functools
 import os
 from typing import Dict, List, Optional
 
+from strictdoc.helpers.path_filter import PathFilter
 from strictdoc.helpers.sorting import alphanumeric_sort
 
 
@@ -28,6 +30,7 @@ class File(FileOrFolderEntry):
         self.full_path = full_path
         self.root_path = full_path
         self.rel_path = rel_path
+        self.file_name = os.path.basename(self.full_path)
         self.files = [self]
         self.subfolder_trees = []
 
@@ -44,7 +47,7 @@ class File(FileOrFolderEntry):
         return self.level
 
     def get_file_name(self) -> str:
-        return os.path.basename(self.full_path)
+        return self.file_name
 
     def get_folder_path(self) -> str:
         return os.path.dirname(self.full_path)
@@ -63,8 +66,8 @@ class Folder(FileOrFolderEntry):  # pylint: disable=too-many-instance-attributes
         self.rel_path: str = rel_path if rel_path != "." else ""
         self.folder_name: str = os.path.basename(os.path.normpath(root_path))
         self.level = level
-        self.files = []
-        self.subfolder_trees = []
+        self.files: List[File] = []
+        self.subfolder_trees: List[Folder] = []
         self.parent_folder: Optional[Folder] = None
         self.has_sdoc_content = False
 
@@ -150,12 +153,24 @@ class FileTree:
 class FileFinder:
     @staticmethod
     def find_files_with_extensions(
-        *, root_path: str, ignored_dirs: List[str], extensions: List[str]
+        *,
+        root_path: str,
+        ignored_dirs: List[str],
+        extensions: List[str],
+        include_paths: List[str],
+        exclude_paths: List[str],
     ):
         assert os.path.isdir(root_path)
         assert os.path.isabs(root_path)
         assert isinstance(extensions, list), extensions
 
+        extensions_tuple = tuple(extensions)
+        path_filter_includes = PathFilter(
+            include_paths, positive_or_negative=True
+        )
+        path_filter_excludes = PathFilter(
+            exclude_paths, positive_or_negative=False
+        )
         root_level: int = root_path.count(os.sep)
 
         root_folder: Folder = Folder(root_path, ".", 0)
@@ -169,16 +184,12 @@ class FileFinder:
             dirs[:] = [
                 d
                 for d in dirs
-                if (
-                    not d.startswith(".")
-                    and not d.startswith("_")
-                    and "tests" not in d
-                    and "integration" not in d
-                )
+                if (not d.startswith(".") and not d.startswith("_"))
             ]
             dirs.sort(key=alphanumeric_sort)
 
             rel_path = os.path.relpath(current_root_path, start=root_path)
+            rel_path = rel_path if rel_path != "." else ""
 
             current_root_path_level: int = (
                 current_root_path.count(os.sep) - root_level
@@ -189,18 +200,33 @@ class FileFinder:
                 Folder(current_root_path, rel_path, current_root_path_level),
             )
 
-            def filter_source_files(_files):
-                _source_files = []
-                for file in _files:
-                    for file_extension in extensions:
-                        if file.endswith(file_extension):
-                            _source_files.append(file)
-                return _source_files
-
-            files = filter_source_files(files)
-            files.sort(key=alphanumeric_sort)
-            current_tree.set(files)
-            if len(files) > 0:
+            for file in files:
+                if not file.endswith(extensions_tuple):
+                    continue
+                full_file_path = os.path.join(current_root_path, file)
+                rel_file_path = os.path.join(rel_path, file)
+
+                if path_filter_excludes.match(rel_file_path):
+                    continue
+
+                if path_filter_includes.match(rel_file_path):
+                    current_tree.files.append(
+                        File(
+                            current_tree.level + 1,
+                            full_file_path,
+                            rel_file_path,
+                        )
+                    )
+
+            def file_path_sort_key(lhs: File, rhs: File):
+                return (rhs.file_name < lhs.file_name) - (
+                    lhs.file_name < rhs.file_name
+                )
+
+            sort_key = functools.cmp_to_key(file_path_sort_key)
+            current_tree.files.sort(key=sort_key)
+
+            if len(current_tree.files) > 0:
                 current_tree.has_sdoc_content = True
 
             if current_root_path == root_path:

{strictdoc-0.0.42a2 → strictdoc-0.0.42a5}/strictdoc/core/finders/source_files_finder.py

@@ -5,6 +5,7 @@ from typing import List
 
 from strictdoc.cli.cli_arg_parser import ExportCommandConfig
 from strictdoc.core.file_tree import File, FileFinder
+from strictdoc.core.project_config import ProjectConfig
 from strictdoc.core.source_tree import SourceTree
 from strictdoc.helpers.auto_described import auto_described
 
@@ -90,7 +91,10 @@ class SourceFile:  # pylint: disable=too-many-instance-attributes
 
 class SourceFilesFinder:
     @staticmethod
-    def find_source_files(config: ExportCommandConfig) -> SourceTree:
+    def find_source_files(
+        config: ExportCommandConfig,
+        project_config: ProjectConfig,
+    ) -> SourceTree:
         map_file_to_source = {}
         found_source_files: List[SourceFile] = []
 
@@ -107,6 +111,8 @@ class SourceFilesFinder:
             root_path=doctree_root_abs_path,
             ignored_dirs=[config.output_dir],
             extensions=SourceFileType.all(),
+            include_paths=project_config.include_source_paths,
+            exclude_paths=project_config.exclude_source_paths,
         )
         root_level = doctree_root_abs_path.count(os.sep)
 

{strictdoc-0.0.42a2 → strictdoc-0.0.42a5}/strictdoc/core/project_config.py

@@ -6,6 +6,7 @@ from typing import List
 import toml
 
 from strictdoc.helpers.auto_described import auto_described
+from strictdoc.helpers.path_filter import validate_mask
 
 
 class ProjectFeature(str, Enum):
@@ -28,7 +29,7 @@ class ProjectFeature(str, Enum):
 
 
 @auto_described
-class ProjectConfig:
+class ProjectConfig:  # pylint: disable=too-many-instance-attributes
     DEFAULT_PROJECT_TITLE = "Untitled Project"
     DEFAULT_DIR_FOR_SDOC_ASSETS = "_static"
     DEFAULT_FEATURES: List[str] = [
@@ -46,12 +47,20 @@ class ProjectConfig:
         project_features: List[str],
         server_host: str,
         server_port: int,
+        include_doc_paths: List[str],
+        exclude_doc_paths: List[str],
+        include_source_paths: List[str],
+        exclude_source_paths: List[str],
     ):
         self.project_title: str = project_title
         self.dir_for_sdoc_assets: str = dir_for_sdoc_assets
         self.project_features: List[str] = project_features
         self.server_host: str = server_host
         self.server_port: int = server_port
+        self.include_doc_paths: List[str] = include_doc_paths
+        self.exclude_doc_paths: List[str] = exclude_doc_paths
+        self.include_source_paths: List[str] = include_source_paths
+        self.exclude_source_paths: List[str] = exclude_source_paths
 
     @staticmethod
     def default_config():
@@ -61,6 +70,10 @@ class ProjectConfig:
             project_features=ProjectConfig.DEFAULT_FEATURES,
             server_host=ProjectConfig.DEFAULT_SERVER_HOST,
             server_port=ProjectConfig.DEFAULT_SERVER_PORT,
+            include_doc_paths=[],
+            exclude_doc_paths=[],
+            include_source_paths=[],
+            exclude_source_paths=[],
         )
 
     def is_feature_activated(self, feature: ProjectFeature):
@@ -124,6 +137,10 @@ class ProjectConfigLoader:
         project_features = ProjectConfig.DEFAULT_FEATURES
         server_host = ProjectConfig.DEFAULT_SERVER_HOST
         server_port = ProjectConfig.DEFAULT_SERVER_PORT
+        include_doc_paths = []
+        exclude_doc_paths = []
+        include_source_paths = []
+        exclude_source_paths = []
 
         if "project" in config_dict:
             project_content = config_dict["project"]
@@ -147,6 +164,62 @@ class ProjectConfigLoader:
                     )
                     sys.exit(1)
 
+            include_doc_paths = project_content.get(
+                "include_doc_paths", include_doc_paths
+            )
+            assert isinstance(include_doc_paths, list)
+            for include_doc_path in include_doc_paths:
+                try:
+                    validate_mask(include_doc_path)
+                except SyntaxError as exception:
+                    print(  # noqa: T201
+                        f"error: strictdoc.toml: 'include_doc_paths': "
+                        f"{exception} Provided string: '{include_doc_path}'."
+                    )
+                    sys.exit(1)
+
+            exclude_doc_paths = project_content.get(
+                "exclude_doc_paths", exclude_doc_paths
+            )
+            assert isinstance(exclude_doc_paths, list)
+            for exclude_doc_path in exclude_doc_paths:
+                try:
+                    validate_mask(exclude_doc_path)
+                except SyntaxError as exception:
+                    print(  # noqa: T201
+                        f"error: strictdoc.toml: 'exclude_doc_paths': "
+                        f"{exception} Provided string: '{exclude_doc_path}'."
+                    )
+                    sys.exit(1)
+
+            include_source_paths = project_content.get(
+                "include_source_paths", include_source_paths
+            )
+            assert isinstance(include_source_paths, list)
+            for include_source_path in include_source_paths:
+                try:
+                    validate_mask(include_source_path)
+                except SyntaxError as exception:
+                    print(  # noqa: T201
+                        f"error: strictdoc.toml: 'include_source_paths': "
+                        f"{exception} Provided string: '{include_source_path}'."
+                    )
+                    sys.exit(1)
+
+            exclude_source_paths = project_content.get(
+                "exclude_source_paths", exclude_source_paths
+            )
+            assert isinstance(exclude_source_paths, list)
+            for exclude_source_path in exclude_source_paths:
+                try:
+                    validate_mask(exclude_source_path)
+                except SyntaxError as exception:
+                    print(  # noqa: T201
+                        f"error: strictdoc.toml: 'exclude_source_paths': "
+                        f"{exception} Provided string: '{exclude_source_path}'."
+                    )
+                    sys.exit(1)
+
         if "server" in config_dict:
             # FIXME: Introduce at least a basic validation for the host/port.
             server_content = config_dict["server"]
@@ -162,4 +235,8 @@ class ProjectConfigLoader:
             project_features=project_features,
             server_host=server_host,
             server_port=server_port,
+            include_doc_paths=include_doc_paths,
+            exclude_doc_paths=exclude_doc_paths,
+            include_source_paths=include_source_paths,
+            exclude_source_paths=exclude_source_paths,
         )

{strictdoc-0.0.42a2 → strictdoc-0.0.42a5}/strictdoc/core/traceability_index_builder.py

@@ -65,7 +65,7 @@ class TraceabilityIndexBuilder:
         )
 
         document_tree, asset_dirs = DocumentFinder.find_sdoc_content(
-            config, parallelizer
+            config, project_config=project_config, parallelizer=parallelizer
         )
 
         # TODO: This is rather messy but it is better than it used to be.
@@ -135,7 +135,7 @@ class TraceabilityIndexBuilder:
             or config.experimental_enable_file_traceability
         ):
             source_tree: SourceTree = SourceFilesFinder.find_source_files(
-                config
+                config, project_config=project_config
             )
             source_files = source_tree.source_files
             source_file: SourceFile
@@ -233,8 +233,8 @@ class TraceabilityIndexBuilder:
                             "error: DocumentIndex: "
                             "two nodes with the same UID "
                             "exist in two different documents: "
-                            f'{node.reserved_uid} in "{document.title}" and '
-                            f'"{other_req_doc.title}".'
+                            f'{node.reserved_uid} in "{other_req_doc.title}" '
+                            f'and "{document.title}".'
                         )
                     sys.exit(1)
                 d_02_requirements_map[

strictdoc-0.0.42a5/strictdoc/helpers/path_filter.py

@@ -0,0 +1,76 @@
+import re
+from typing import List
+
+REGEX_NAME_PART = r"[A-Za-z0-9-_\.]+"
+REGEX_FILENAME = rf"{REGEX_NAME_PART}"
+REGEX_FOLDER = rf"{REGEX_NAME_PART}"
+
+REGEX_WILDCARD = REGEX_FILENAME
+# FIXME: This does the job but most probably could be simplified.
+REGEX_DOUBLE_WILDCARD = (
+    rf"(\\|\/)?({REGEX_NAME_PART})?((\\|\/){REGEX_NAME_PART})*(\\|\/)?"
+)
+
+REGEX_MASK_VALIDATION = rf"[^(\\|\/)]{REGEX_DOUBLE_WILDCARD}"
+
+MOST_COMMON_CHARACTERS = ("[", "]", "(", ")", "{", "}", "?", "+", "!")
+
+
+def validate_mask(mask: str):
+    if mask == "":
+        raise SyntaxError("Path mask must not be empty.")
+
+    if not mask[0].isalnum() and mask[0] != "*":
+        raise SyntaxError(
+            "Path mask must start with an alphanumeric character or "
+            "a wildcard symbol '*'."
+        )
+
+    if "//" in mask or "\\\\" in mask:
+        raise SyntaxError("Path mask must not contain double slashes.")
+
+    if "***" in mask:
+        raise SyntaxError("Invalid wildcard: '***'.")
+
+    for regex_symbol in MOST_COMMON_CHARACTERS:
+        if regex_symbol in mask:
+            raise SyntaxError(
+                f"Path mask must not contain any of the special characters: "
+                f"{MOST_COMMON_CHARACTERS}."
+            )
+
+
+def compile_regex_mask(path_mask: str) -> str:
+    regex_mask = path_mask
+    regex_mask = regex_mask.replace(".", "\\.")
+    regex_mask = regex_mask.replace("**", "XXXX")
+    regex_mask = regex_mask.replace("*", REGEX_WILDCARD)
+    regex_mask = regex_mask.replace("XXXX", REGEX_DOUBLE_WILDCARD)
+    # Support files like "file1.py" and "./file1.py"
+    regex_mask = "^" + "(\\.\\/)?" + regex_mask + "$"  # noqa: ISC003
+    return regex_mask
+
+
+class PathFilter:
+    def __init__(self, filtered_paths: List[str], positive_or_negative: bool):
+        self.filtered_paths: List[str] = filtered_paths
+        self.compiled_regex_masks: List[str] = []
+        for filtered_path in filtered_paths:
+            validate_mask(filtered_path)
+            self.compiled_regex_masks.append(compile_regex_mask(filtered_path))
+        self.positive_or_negative: bool = positive_or_negative
+
+    def match(self, found_path: str) -> bool:
+        # If this is an empty positive filter, we want to match everything
+        # positively. If this is an empty negative filter, we want to match
+        # everything negatively.
+        if len(self.filtered_paths) == 0:
+            return self.positive_or_negative
+
+        portable_found_path = found_path.replace("\\", "/")
+        for regex_mask in self.compiled_regex_masks:
+            regex_match = re.match(regex_mask, portable_found_path)
+            if regex_match is not None:
+                return True
+
+        return False

strictdoc-0.0.42a5/strictdoc.toml

@@ -0,0 +1,24 @@
+[project]
+title = "StrictDoc Documentation"
+html_assets_strictdoc_dir = "assets"
+
+features = [
+  "TABLE_SCREEN",
+  "TRACEABILITY_SCREEN",
+  "DEEP_TRACEABILITY_SCREEN",
+  # "REQUIREMENT_TO_SOURCE_TRACEABILITY"
+]
+
+include_doc_paths = [
+  "docs/**"
+]
+
+exclude_doc_paths = [
+  "tests/**"
+]
+
+include_source_paths = [
+  "strictdoc/**"
+]
+
+exclude_source_paths = []