Source code linker partial re-write (#125)

* Re-engineered working of source code linker
* Adapted tests to conform to new working of the extension
* Changed parsing & writing of json
* Small adaptation in README

---------

Co-authored-by: Alexander Lanin <Alexander.Lanin@bosch.com>

Author: MaximilianSoerenPollak

docs.bzl

@@ -44,7 +44,6 @@ load("@rules_pkg//pkg:mappings.bzl", "pkg_files")
 load("@rules_pkg//pkg:tar.bzl", "pkg_tar")
 load("@rules_python//sphinxdocs:sphinx.bzl", "sphinx_build_binary", "sphinx_docs")
 load("@rules_python//sphinxdocs:sphinx_docs_library.bzl", "sphinx_docs_library")
-load("@score_docs_as_code//src/extensions/score_source_code_linker:collect_source_files.bzl", "parse_source_files_for_needs_links")
 load("@score_python_basics//:defs.bzl", "score_virtualenv")
 
 sphinx_requirements = all_requirements + [
@@ -66,13 +65,6 @@ def docs(source_files_to_scan_for_needs_links = None, source_dir = "docs", conf_
     * only callable from 'docs/BUILD'
     """
 
-    # Parse source files for needs links
-    # This needs to be created to generate a target, otherwise it won't execute as dependency for other macros
-    parse_source_files_for_needs_links(
-        name = "score_source_code_parser",
-        srcs_and_deps = source_files_to_scan_for_needs_links if source_files_to_scan_for_needs_links else [],
-    )
-
     # We are iterating over all provided 'targets' in order to allow for automatic generation of them without
     # needing to modify the underlying 'docs.bzl' file.
     for target in docs_targets:
@@ -137,7 +129,7 @@ def _incremental(incremental_name = "incremental", live_name = "live_preview", s
         srcs = ["@score_docs_as_code//src:incremental.py"],
         deps = dependencies,
         # TODO: Figure out if we need all dependencies as data here or not.
-        data = [":score_source_code_parser", "@score_docs_as_code//src:plantuml", "@score_docs_as_code//src:docs_assets"] + dependencies + external_needs_deps,
+        data = ["@score_docs_as_code//src:plantuml", "@score_docs_as_code//src:docs_assets"] + dependencies + external_needs_deps,
         env = {
             "SOURCE_DIRECTORY": source_dir,
             "CONF_DIRECTORY": conf_dir,
@@ -205,7 +197,6 @@ def _docs(name = "docs", suffix = "", format = "html", external_needs_deps = lis
             "manual",
         ],
         tools = [
-            ":score_source_code_parser",
             "@score_docs_as_code//src:plantuml",
             "@score_docs_as_code//src:docs_assets",
         ] + external_needs_deps,

docs/BUILD

@@ -48,7 +48,4 @@ docs(
         },
     ],
     source_dir = "docs",
-    source_files_to_scan_for_needs_links = [
-        "//src:score_extension_files",
-    ],
 )

docs/product/extensions/source_code_linker.md

@@ -16,7 +16,7 @@ The extension uses two main components to integrate with Bazel:
    - Handles dependency tracking for incremental builds
 
 2. `parse_source_files.py`
-   - Scans input files for template tags (e.g., `# req-traceability:`)
+   - Scans input files for template tags (e.g., "#<!-- comment prevents parsing this occurance --> req-traceability:")
    - Retrieves git information (hash, file location)
    - Generates mapping file with requirement IDs and links
 
@@ -37,16 +37,26 @@ The extension uses two main components to integrate with Bazel:
        - Gets current git hash for each file
        - Constructs GitHub URLs with format:
          `{base_url}/{repo}/blob/{hash}/{file}#L{line_nr}`
-        **Note:** The base_url is defined in `parse_source_files.py`. Currently set to: `https://github.com/eclipse-score/score/blob/`  
+        **Note:** The base_url is defined in `parse_source_files.py`. Currently set to: `https://github.com/eclipse-score/score/blob/`
 
 Produces JSON mapping file:
 ```json
-{
-    "REQ_ID": [
-        "github_link1",
-        "github_link2"  // If multiple code-links exist
-    ]
-}
+[
+    {
+        "file": "src/implementation1.py",
+        "line": 3,
+        "tag":"# req-Id:",
+        "need": "TREQ_ID_1",
+        "full_line": "# req-Id: TREQ_ID_1"
+    },
+    {
+        "file": "src/implementation2.py", 
+        "line": 3,
+        "tag":"# req-Id:",
+        "need": "TREQ_ID_1",
+        "full_line": "# req-Id: TREQ_ID_1"
+    },
+]
 ```
 
 <br>
@@ -86,7 +96,7 @@ The extension hooks into Sphinx's build process. It attaches to the `env-updated
 
 ### Adding Places to Search
 
-You can easily add files to be searched by adding targets / files to the deps inside the 
+You can easily add files to be searched by adding targets / files to the deps inside the
 `collect_source_files_for_score_source_code_linker` in `docs/BUILD`.
 See here:
 
@@ -126,7 +136,7 @@ WARNING: Could not find TREQ_ID_200 in the needs id's. Found in file(s):['_tooli
 
 ### Quickly Finding Source Links
 
-The easiest and quickest way to find source_code_link options is to just search for the option `source_code_link`. It should give you all rst files 
+The easiest and quickest way to find source_code_link options is to just search for the option `source_code_link`. It should give you all rst files
 where the option is not empty.
 
 ### Executing Tests

src/extensions/score_metamodel/__init__.py

@@ -11,18 +11,17 @@
 # SPDX-License-Identifier: Apache-2.0
 # *******************************************************************************
 import importlib
-import pkgutil
 import json
 import os
-
+import pkgutil
 from collections.abc import Callable
 from pathlib import Path
 
-
 from ruamel.yaml import YAML
 from sphinx.application import Sphinx
 from sphinx_needs import logging
-from sphinx_needs.data import NeedsInfoType, SphinxNeedsData, NeedsView
+from sphinx_needs.data import NeedsInfoType, NeedsView, SphinxNeedsData
+
 from .log import CheckLogger
 
 logger = logging.get_logger(__name__)
@@ -81,7 +80,9 @@ def _run_checks(app: Sphinx, exception: Exception | None) -> None:
 
     logger.debug(f"Running checks for {len(needs_all_needs)} needs")
 
-    prefix = str(Path(app.srcdir).relative_to(Path.cwd()))
+    ws_root = os.environ.get("BUILD_WORKSPACE_DIRECTORY", None)
+    cwd_or_ws_root = Path(ws_root) if ws_root else Path.cwd()
+    prefix = str(Path(app.srcdir).relative_to(cwd_or_ws_root))
 
     log = CheckLogger(logger, prefix)
 

src/extensions/score_source_code_linker/BUILD

@@ -29,16 +29,18 @@ py_library(
 score_py_pytest(
     name = "score_source_code_linker_test",
     size = "small",
-    srcs = glob(["tests/**/*.py"]),
+    srcs = glob([
+        "tests/**/*.py",
+        "test/**/*.json",
+    ]),
+    args = [
+        "-s",
+        "-vv",
+    ],
+    data = glob(["**/*.json"]),
+    imports = ["."],
     deps = [
         ":score_source_code_linker",
+        "@score_docs_as_code//src/extensions/score_metamodel",
     ] + all_requirements,
 )
-
-# Needed to make the file parser executeable and findable for the source_code_linker aspect
-py_binary(
-    name = "parsed_source_files_for_source_code_linker",
-    srcs = ["parse_source_files.py"],
-    main = "parse_source_files.py",
-    visibility = ["//visibility:public"],
-)