Merge pull request #2537 from strictdoc-project/stanislaw/validation

feat(core): introduce framework for user-defined plugins

Author: stanislaw

strictdoc/core/plugin.py

@@ -0,0 +1,11 @@
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from strictdoc.core.traceability_index import TraceabilityIndex
+
+
+class StrictDocPlugin:
+    def traceability_index_build_finished(
+        self, traceability_index: "TraceabilityIndex"
+    ) -> None:
+        pass

strictdoc/core/project_config.py

@@ -21,6 +21,7 @@
     ServerCommandConfig,
 )
 from strictdoc.core.environment import SDocRuntimeEnvironment
+from strictdoc.core.plugin import StrictDocPlugin
 from strictdoc.helpers.auto_described import auto_described
 from strictdoc.helpers.exception import StrictDocException
 from strictdoc.helpers.file_modification_time import get_file_modification_time
@@ -134,6 +135,7 @@ def __init__(
             str
         ] = ProjectConfigDefault.DEFAULT_SECTION_BEHAVIOR,
         statistics_generator: Optional[str] = None,
+        user_plugin: Optional[StrictDocPlugin] = None,
         # Reserved for StrictDoc's internal use.
         _config_last_update: Optional[datetime.datetime] = None,
     ) -> None:
@@ -248,6 +250,7 @@ def __init__(
         self.section_behavior: Optional[str] = section_behavior
 
         self.statistics_generator: Optional[str] = statistics_generator
+        self.user_plugin: Optional[StrictDocPlugin] = user_plugin
 
         self.config_last_update: Optional[datetime.datetime] = (
             _config_last_update

strictdoc/core/traceability_index_builder.py

@@ -222,6 +222,11 @@ def create(
             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

tests/integration/features/plugin/01_traceability_index_build_finished/input.sdoc

@@ -0,0 +1,8 @@
+[DOCUMENT]
+TITLE: Hello world doc
+
+[REQUIREMENT]
+TITLE: I am a title with a dot at the end, I will trigger the validation.
+STATEMENT: >>>
+System A shall do B.
+<<<

tests/integration/features/plugin/01_traceability_index_build_finished/strictdoc_config.py

@@ -0,0 +1,16 @@
+import os
+import sys
+
+from strictdoc.core.project_config import ProjectConfig
+
+sys.path.append(os.path.dirname(__file__))
+
+from user_plugin import UserPlugin
+
+
+def create_config() -> ProjectConfig:
+    config = ProjectConfig(
+        project_title="StrictDoc Documentation",
+        user_plugin=UserPlugin()
+    )
+    return config

tests/integration/features/plugin/01_traceability_index_build_finished/test.itest

@@ -0,0 +1,8 @@
+RUN: %strictdoc export %S --output-dir %T | filecheck %s --dump-input=fail
+CHECK: warning: traceability_index_build_finished() is called.
+CHECK: warning: Node title ends with a dot: "I am a title with a dot at the end, I will trigger the validation.".
+CHECK: Published: Hello world doc
+
+RUN: %cat %T/html/index.html | filecheck %s --dump-input=fail --check-prefix CHECK-HTML
+CHECK-HTML: Hello world doc
+CHECK-HTML: input.sdoc

tests/integration/features/plugin/01_traceability_index_build_finished/user_plugin.py

@@ -0,0 +1,23 @@
+from strictdoc.backend.sdoc.models.node import SDocNode
+from strictdoc.core.document_iterator import DocumentCachingIterator
+from strictdoc.core.plugin import StrictDocPlugin
+from strictdoc.core.traceability_index import TraceabilityIndex
+
+
+class UserPlugin(StrictDocPlugin):
+    def traceability_index_build_finished(self, traceability: TraceabilityIndex):
+        print("warning: traceability_index_build_finished() is called.")  # noqa: T201
+
+        for document in traceability.document_tree.document_list:
+            assert document.meta is not None
+
+            document_iterator = DocumentCachingIterator(document)
+
+            for node, _ in document_iterator.all_content(
+                print_fragments=False,
+            ):
+                if not isinstance(node, SDocNode):
+                    continue
+
+                if node.reserved_title.endswith("."):
+                    print(f'warning: Node title ends with a dot: "{node.reserved_title}".')  # noqa: T201