Merge pull request #2621 from strictdoc-project/stanislaw/grammar_from_file

feat(sdoc|project_config): extend DOCUMENT_FROM_FILE to support grammar aliases

Author: stanislaw

.gitignore

@@ -13,6 +13,8 @@
 **/.sandbox/**
 __pycache__
 
+/tests/unit_server/**/output/
+
 ### LIT/FileCheck integration tests' artifacts. ###
 /tests/integration/**/Output/**
 /tests/integration/**/sandbox/

.link_health.yml

@@ -34,3 +34,4 @@ exceptions:
   - url: https://github.com/tiangolo/fastapi/blob/master/LICENSE
   - url: https://github.com/strictdoc-project/strictdoc/blob/main/about/2025_ESA_SW_Product_Assurance_Workshop.pdf
   - url: https://github.com/strictdoc-project/strictdoc/blob/main/strictdoc/core/project_config.py
+  - url: https://github.com/strictdoc-project/strictdoc/blob/main/strictdoc_config.py

docs/strictdoc_01_user_guide.sdoc

@@ -2193,6 +2193,47 @@ When a ``[GRAMMAR]`` is declared with an ``IMPORT_FROM_FILE`` line, the grammar
     Editing of the grammars defined in ``.sgra`` files can be only done with a text editor, it is not implemented yet in the editable web interface.
 <<<
 
+[[SECTION]]
+MID: 00d5670e058d43b1b293da87e22c3a26
+TITLE: Grammar aliases
+
+[TEXT]
+MID: eba1c3f3a9364f1c8785c30c6fa5f3cc
+STATEMENT: >>>
+To support sharing a grammar across multiple documents, possibly located in different directories, a grammar alias can be used as follows:
+
+.. code-block: strictdoc
+
+    [DOCUMENT]
+    TITLE: Hello world
+
+    [GRAMMAR]
+    IMPORT_FROM_FILE: @my_grammar
+
+The grammar alias itself must be registered in the project config:
+
+.. code-block:: python
+
+    from strictdoc.core.project_config import ProjectConfig
+
+
+    def create_config() -> ProjectConfig:
+        config = ProjectConfig(
+            project_title="StrictDoc Documentation",
+            project_features=[
+                # Intentionally nothing.
+            ],
+            grammars={
+                "@my_grammar": "grammar.sgra",
+            },
+        )
+        return config
+
+The grammar path must be specified relative to the directory containing the project configuration file.
+<<<
+
+[[/SECTION]]
+
 [[/SECTION]]
 
 [[/SECTION]]

docs/strictdoc_04_release_notes.sdoc

@@ -57,6 +57,15 @@ This release contains the following enhancements:
 1\) The code block syntax highlighting has been enabled for all RST ``.. code::`` blocks. The code blocks that have been tested already include C, TOML, and Python.
 
 Also, a Pygments lexer for the SDoc markup has been added to the StrictDoc source code. From now on, ``.. code:: strictdoc`` blocks are recognized and syntax-highlighted.
+
+2\) The grammar aliases were added to allow importing a single grammar from multiple SDoc documents located in different directories. From now on, it is possible to register a grammar alias and its path in a project configuration file and use it as follows:
+
+.. code-block:: strictdoc
+
+    [GRAMMAR]
+    IMPORT_FROM_FILE: @my_grammar
+
+Thanks to @gregshue for requesting this feature and explaining the need for it.
 <<<
 
 [[/SECTION]]

strictdoc/backend/sdoc/processor.py

@@ -1,4 +1,5 @@
 import os.path
+import re
 from typing import Any, Callable, Dict, List, Optional, Union, cast
 
 from textx import TextXSyntaxError, get_model
@@ -89,6 +90,14 @@ def process_document_grammar(
     ) -> None:
         assert self.parse_context.document_config is not None
 
+        if (import_from_file_ := document_grammar.import_from_file) is not None:
+            if re.search(r"\.\.|[/\\]", import_from_file_):
+                raise StrictDocException(
+                    "[GRAMMAR]: "
+                    "IMPORT_FROM_FILE must not contain any '..', '/', '\\' characters: "
+                    f"{import_from_file_}."
+                )
+
         preserve_source_location_data(document_grammar)
         # FIXME: It would be great to move forward and remove this.
         if not document_grammar.has_text_element():

strictdoc/cli/main.py

@@ -81,7 +81,6 @@ def _main_internal(parallelizer: Parallelizer, parser: SDocArgsParser) -> None:
         project_config = ProjectConfigLoader.load_from_path_or_get_default(
             path_to_config=server_config.get_path_to_config(),
         )
-        project_config.validate_and_finalize()
         run_strictdoc_server(
             server_config=server_config, project_config=project_config
         )

strictdoc/core/file_system/document_finder.py

@@ -164,7 +164,9 @@ def _build_document_tree(
             )
 
             if isinstance(document, DocumentGrammar):
-                map_grammars_by_filenames[doc_file.file_name] = document
+                map_grammars_by_filenames[
+                    doc_file.rel_path.relative_path_posix
+                ] = document
                 continue
 
             input_doc_full_path: str = doc_file.full_path

strictdoc/core/project_config.py

@@ -119,6 +119,7 @@ def __init__(
         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,
@@ -202,6 +203,9 @@ def __init__(
         self.exclude_source_paths: List[str] = (
             exclude_source_paths if exclude_source_paths is not None else []
         )
+
+        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 {}
         )
@@ -377,24 +381,45 @@ def integrate_export_config(
             self.reqif_enable_mid = export_config.reqif_enable_mid
 
     def validate_and_finalize(self) -> None:
-        if (input_paths_ := self.input_paths) and len(input_paths_) > 0:
-            path_to_gitignore = os.path.join(self.input_paths[0], ".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)
+        project_path = self.get_project_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 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_}."
+            )
 
     def is_feature_activated(self, feature: ProjectFeature) -> bool:
         return feature in self.project_features
@@ -459,6 +484,11 @@ def is_activated_source_file_language_parsers(self) -> bool:
             ProjectFeature.SOURCE_FILE_LANGUAGE_PARSERS in self.project_features
         )
 
+    def get_project_root_path(self) -> str:
+        if self.input_paths is not None and len(self.input_paths) > 0:
+            return self.input_paths[0]
+        raise NotImplementedError
+
     def get_strictdoc_root_path(self) -> str:
         return self.environment.path_to_strictdoc
 

strictdoc/core/traceability_index_builder.py

@@ -5,6 +5,7 @@
 import datetime
 import glob
 import os
+import posixpath
 import sys
 from typing import Any, Dict, Iterator, List, Optional, Set, Union
 
@@ -378,10 +379,16 @@ def create_from_document_tree(
             # First, resolve all grammars that are imported from grammar files.
             #
             if document.grammar.import_from_file is not None:
-                document_grammar: Optional[DocumentGrammar] = (
-                    document_tree.get_grammar_by_filename(
-                        document.grammar.import_from_file
+                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(

strictdoc/server/server.py

@@ -45,6 +45,7 @@ def run_strictdoc_server(
             )
 
         project_config.integrate_server_config(server_config)
+        project_config.validate_and_finalize()
 
         reload_config = UvicornReloadConfig.create(
             project_config, server_config