Question about line marker specification: @relation(scope=line) targeting behavior

[Mooan]

Hi. I'm evaluating StrictDoc's source code traceability and source code coverage functionality. I have a question regarding the specification and would appreciate clarification.

Background

I've been testing the 5) Linking a single line to a requirement feature described in 10.2. Linking source code to requirements.

While testing this functionality, I observed that the line marker appears to reference the comment line itself (where the @relation marker is placed), rather than the executable code line that follows it.

Question

Which behavior is this feature intended to implement according to the specification?

Option A: The marker references the comment line where it is placed (current observed behavior)
Option B: The marker should reference the executable code line immediately following the marker

Current Behavior Observed

When testing the line marker functionality, the HTML coverage report highlights the comment line containing the @relation marker itself, as shown in the attached screenshot.

Test setup:

environment:

• MacOS Sequoia 15.6
• Python 3.13.0
• strictdoc 0.10.0

strictdoc.toml:

[project]
title = "StrictDoc Documentation"
html_assets_strictdoc_dir = "assets"

features = [
  # Stable features.
  "TABLE_SCREEN",
  "TRACEABILITY_SCREEN",
  "DEEP_TRACEABILITY_SCREEN",

  "MATHJAX",

  # Experimental features are disabled by default.
  # "REQIF",
  # "STANDALONE_DOCUMENT_SCREEN",
  # "REQUIREMENTS_COVERAGE_SCREEN",
  "REQUIREMENT_TO_SOURCE_TRACEABILITY",
  # "HTML2PDF",
]

example.sdoc:

[DOCUMENT]
TITLE: Example: Traceability between requirements and a single line in source file

[REQUIREMENT]
UID: REQ-901
TITLE: A single line requirement
STATEMENT: This requirement traces to a single line of code.

file.py:

def hello_world():
    # @relation(REQ-901, scope=line)
    print("hello world")

Thank you for your time and any guidance you can provide.

[stanislaw]

Hello @Mooan,

thanks for starting this discussion. StrictDoc's backlog is a big pile of different kinds of work. Making line markers behave the way you describe is on my TODO list, but it has a low priority (there is not even an open ticket for it). In fact, the parser could support both behaviors:

• Option A: The marker references the comment line where it is placed (the current behavior).
• Option B: The marker references the executable code line immediately following the marker.

The reason I haven’t prioritized this is that a line marker is just a special case of a range marker. So in the worst case, you can simply replace a line marker with a range marker.

How important is this feature for you? I will not get to doing it myself within a few weeks but I could support you with contributing the option B parsing behavior.

Note that there can be open questions related to the behavior of the Option B: what if marker is followed by several consecutive lines of code — does it mean that we want them all to be included? It seems to be nice but then it no longer feels like a line marker 🤔

[Mooan]

Hello @stanislaw

Thank you for your thoughtful response!

Importance of LineMarker:

We are considering using StrictDoc to manage traceability and coverage between requirements and source code.
RangeMarker works for our use cases, but requiring two lines to reference a single line of code feels redundant.

For our use case, adopting LineMarker with Option B would provide the following benefits:

Conciseness: A single line of code can be referenced with a single line marker
Consistency: RangeMarker and LineMarker would have consistent notation, making coverage management easier

Please find the behavioral concept attached below:

As a proof of concept, I have implemented the behavioral concept (for now, only the normal case behavior):

Mooan@6375ee5

Thanks.

[stanislaw]

@Mooan I have given some thought to this topic and I think we could just implement it using your option B and remove the option A because indeed the option B is stronger for most of the real-world uses. Would you mind opening a Pull Request with your changes?

[Mooan]

@stanislaw

Thanks for the feedback!
I'll work on preparing a Pull Request. I just need a bit of time to go through the contribution guidelines and get my testing environment ready. I really appreciate your time on this!