Implement validity attributes (#274)

Derive requirements for validity attributes introduced in score_process 1.2.0.

Author: a-zw

MODULE.bazel

@@ -13,7 +13,7 @@
 
 module(
     name = "score_docs_as_code",
-    version = "1.3.0",
+    version = "1.4.0",
     compatibility_level = 1,
 )
 

docs/requirements/requirements.rst

@@ -427,6 +427,32 @@ Mapping
      No concept yet
 
 
+.. tool_req:: Enforce validity attribute correctness
+  :id: tool_req__docs_req_attr_validity_correctness
+  :tags: Requirements
+  :implemented: PARTIAL
+  :parent_covered: YES
+  :satisfies: PROCESS_gd_req__req_validity
+  :status: valid
+
+  Docs-as-Code shall enforce that the ``valid_from`` and ``valid_until`` attributes of stakeholder and feature requirements are correct.
+
+  The format of a milestone is something like "v0.5" or "v1.0.1".
+  No suffixes like "-SNAPSHOT" or "-beta" are allowed.
+
+.. tool_req:: Enforce validity start is before end
+  :id: tool_req__docs_req_attr_validity_consistency
+  :tags: Requirements
+  :implemented: PARTIAL
+  :parent_covered: YES
+  :satisfies: PROCESS_gd_req__req_validity
+  :status: valid
+
+  Docs-as-Code shall enforce that ``valid_from`` is before ``valid_until`` attribute in stakeholder and feature requirements.
+  We consider "from" is inclusive but "until" is exclusive, so from v0.5 until v1.0 means valid for v0.5 but not for v1.0.
+  If either attribute is missing, no check is performed.
+
+
 -------------------------
 🔗 Links
 -------------------------

src/extensions/score_metamodel/__init__.py

@@ -62,7 +62,8 @@ def parse_checks_filter(filter: str) -> list[str]:
     }
     for check in checks:
         assert check in all_check_names, (
-            f"Check: '{check}' is not one of the defined local or graph checks"
+            f"Check: '{check}' is not one of the defined local or graph checks: "
+            + ", ".join(all_check_names)
         )
 
     return checks

src/extensions/score_metamodel/checks/check_options.py

@@ -207,3 +207,43 @@ def check_extra_options(
         extra_options_str = ", ".join(f"`{option}`" for option in extra_options)
         msg = f"has these extra options: {extra_options_str}."
         log.warning_for_need(need, msg)
+
+
+def parse_milestone(value: str) -> tuple[int, int, int]:
+    """Parse a string like 'v0.5' or 'v1.0.0'. No suffixes."""
+    match = re.match(r"v(\d+)(\.(\d+))?(\.(\d+))?$", value)
+    if not match:
+        raise ValueError(f"Invalid milestone format: {value}")
+    major = int(match.group(1))
+    minor = int(match.group(3) or 0)
+    patch = int(match.group(5) or 0)
+    return (major, minor, patch)
+
+
+# req-Id: tool_req__docs_req_attr_validity_consistency
+@local_check
+def check_validity_consistency(
+    app: Sphinx,
+    need: NeedsInfoType,
+    log: CheckLogger,
+):
+    """
+    Check if the attributes valid_from < valid_until.
+    """
+    if need["type"] not in ("stkh_req", "feat_req"):
+        return
+
+    valid_from = need.get("valid_from", None)
+    valid_until = need.get("valid_until", None)
+
+    if not valid_from or not valid_until:
+        return
+
+    valid_from_version = parse_milestone(valid_from)
+    valid_until_version = parse_milestone(valid_until)
+    if valid_from_version >= valid_until_version:
+        msg = (
+            "inconsistent validity: "
+            f"valid_from ({valid_from}) >= valid_until ({valid_until})."
+        )
+        log.warning_for_need(need, msg)

src/extensions/score_metamodel/metamodel.yaml

@@ -261,6 +261,9 @@ needs_types:
       # req-Id: tool_req__docs_req_attr_testcov
       testcovered: ^(YES|NO)$
       hash: ^.*$
+      # req-Id: tool_req__docs_req_attr_validity_correctness
+      valid_from: ^v(0|[1-9]\d*)\.(0|[1-9]\d*)(\.(0|[1-9]\d*))?$
+      valid_until: ^v(0|[1-9]\d*)\.(0|[1-9]\d*)(\.(0|[1-9]\d*))?$
     tags:
       - requirement
       - requirement_excl_process
@@ -291,6 +294,9 @@ needs_types:
       # req-Id: tool_req__docs_req_attr_testcov
       testcovered: ^(YES|NO)$
       hash: ^.*$
+      # req-Id: tool_req__docs_req_attr_validity_correctness
+      valid_from: ^v(0|[1-9]\d*)\.(0|[1-9]\d*)(\.(0|[1-9]\d*))?$
+      valid_until: ^v(0|[1-9]\d*)\.(0|[1-9]\d*)(\.(0|[1-9]\d*))?$
     tags:
       - requirement
       - requirement_excl_process

src/extensions/score_metamodel/tests/rst/attributes/test_validity.rst

@@ -0,0 +1,38 @@
+..
+   # *******************************************************************************
+   # Copyright (c) 2025 Contributors to the Eclipse Foundation
+   #
+   # See the NOTICE file(s) distributed with this work for additional
+   # information regarding copyright ownership.
+   #
+   # This program and the accompanying materials are made available under the
+   # terms of the Apache License Version 2.0 which is available at
+   # https://www.apache.org/licenses/LICENSE-2.0
+   #
+   # SPDX-License-Identifier: Apache-2.0
+   # *******************************************************************************
+#CHECK: check_validity_consistency
+
+
+#EXPECT: feat_req__random_id1: inconsistent validity: valid_from (v1.0) >= valid_until (v0.5).
+
+.. feat_req:: from after until
+   :id: feat_req__random_id1
+   :valid_from: v1.0
+   :valid_until: v0.5
+
+
+#EXPECT-NOT: feat_req__random_id2: inconsistent validity: valid_from (v0.5) >= valid_until (v1.0).
+
+.. feat_req:: until after from
+   :id: feat_req__random_id2
+   :valid_from: v0.5
+   :valid_until: v1.0
+
+
+#EXPECT: stkh_req__random_id1: inconsistent validity: valid_from (v1.0.1) >= valid_until (v0.5).
+
+.. stkh_req:: from after until for stakeholder requirement
+   :id: stkh_req__random_id1
+   :valid_from: v1.0.1
+   :valid_until: v0.5

src/extensions/score_metamodel/tests/rst/options/test_options_options.rst

@@ -504,3 +504,17 @@
 
 .. std_wp:: This is a test
    :id: std_wp__test_content
+
+
+#EXPECT: feat_req__random_id3.valid_from (2035-03): does not follow pattern
+
+.. feat_req:: milestone must be a version
+   :id: feat_req__random_id3
+   :valid_from: 2035-03
+
+
+#EXPECT: feat_req__random_id4.valid_until (2035-03): does not follow pattern
+
+.. feat_req:: milestone must be a version
+   :id: feat_req__random_id4
+   :valid_until: 2035-03

src/extensions/score_metamodel/tests/test_check_options.py

@@ -20,6 +20,7 @@
 from score_metamodel.checks.check_options import (
     check_extra_options,
     check_options,
+    parse_milestone,
 )
 from score_metamodel.tests import fake_check_logger, need
 from sphinx.application import Sphinx  # type: ignore[import-untyped]
@@ -118,3 +119,9 @@ def test_unknown_option_present_in_neither_req_opt_neither_opt_opt(self):
             "has these extra options: `other_option`.",
             expect_location=False,
         )
+
+
+def test_milestone_parsing():
+    assert parse_milestone("v0.5") == (0, 5, 0)
+    assert parse_milestone("v1.0") == (1, 0, 0)
+    assert parse_milestone("v1.0.1") == (1, 0, 1)