feat: scope verification reports to a report_version via valid_from by antonkri · Pull Request #843 · eclipse-score/docs-as-code

antonkri · 2026-09-21T06:56:46Z

Stacked on #839 (targets that branch, not main, so the diff here only shows the two commits below; it will show against main once #839 merges and this PR's base is retargeted).

Why

module_verification_report and platform_verification_report (see #839) always show every Requirement/Feature/Component in the current build. There is no way to scope either report to "everything relevant for release X", even though the metamodel already has a valid_from/valid_until attribute on feat_req/stkh_req for exactly this purpose (see tool_req__docs_req_attr_validity_correctness).

What changed

src/extensions/score_metamodel/metamodel.yaml: new optional report_version attribute on the document need type, using the same vMAJOR.MINOR[.PATCH] format already enforced for valid_from/valid_until.
src/extensions/score_sphinx_needs_templates/__init__.py: two new render-context helpers.
- req_in_scope(need, report_version) decides whether a single requirement Need is in scope. feat_req/stkh_req carry valid_from directly; comp_req has no valid_from of its own, so it inherits scope from the feat_req it is derived_from. A requirement with no resolvable valid_from is excluded whenever a report_version is set.
- any_req_in_scope(reqs, report_version) decides whether a Feature/Component has any requirement in scope.
src/needs_templates/module_verification_report.need and src/needs_templates/platform_verification_report.need use these helpers to:
- restrict the Requirements Statistics needpies and the requirements needtable to id in [...] the in-scope requirement IDs, and
- drop a Feature/Component from the report entirely (Overview table and its whole detail section) when none of its requirements are in scope, instead of rendering an empty section.
An unset/empty report_version keeps a report fully unscoped (all Features/Components/requirements shown), which is what doc__platform_verification_report_latest and similar "latest" reports rely on — this is opt-in and backward compatible.

github-actions · 2026-09-21T07:11:37Z

Documentation preview for this pull request is available at:
pr-843: https://eclipse-score.github.io/docs-as-code/pr-843/

antonkri · 2026-09-21T07:38:51Z

@AlexanderLanin as requested, please review

Copilot

Copilot review overview

🟡 Changes recommended

Release scoping ignores the exclusive valid_until boundary and lacks focused behavioral tests.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1 · 1

Open (2)

Enforce exclusive valid_until in release scoping · New
Add tests for release scoping and requirement inheritance · New

What changed in this PR

Adds opt-in release-version scoping to module and platform verification reports.

Changes:

Adds report_version metadata and requirement-scope helpers.
Filters report sections, statistics, and tables by requirement validity.
Updates generated Needs JSON fixtures.

File	Description
`src/extensions/score_metamodel/metamodel.yaml`	Defines `report_version`.
`src/extensions/score_sphinx_needs_templates/__init__.py`	Implements scope helpers.
`src/needs_templates/module_verification_report.need`	Scopes component reporting.
`src/needs_templates/platform_verification_report.need`	Scopes feature reporting.
`src/tests/docs_bzl/scenarios/basic_docs/_expected/needs_json/needs.json`	Updates expected schema.
`src/tests/docs_bzl/scenarios/data_files_runfiles/_expected/data_bundle_needs/needs.json`	Updates expected schema.
`src/tests/docs_bzl/scenarios/data_files_runfiles/_expected/isolated_source_bundle_needs/needs.json`	Updates expected schema.
`src/tests/docs_bzl/scenarios/data_files_runfiles/_expected/needs_json/needs.json`	Updates expected schema.
`src/tests/docs_bzl/scenarios/nested_bundles/_expected/needs_json/needs.json`	Updates expected schema.
`src/tests/docs_bzl/scenarios/reference_integration/_expected/needs_local.json`	Updates expected schema.
`src/tests/docs_bzl/scenarios/reference_integration/legacy_module/_expected/needs_json/needs.json`	Updates expected schema.
`src/tests/docs_bzl/scenarios/reference_integration/legacy_module/docs/components/component/_expected/needs_local.json`	Updates expected schema.
`src/tests/docs_bzl/scenarios/reference_integration/modern_module/_expected/needs_json/needs.json`	Updates expected schema.
`src/tests/docs_bzl/scenarios/reference_integration/modern_module/docs/components/unlinked_component/_expected/needs_local.json`	Updates expected schema.
`src/tests/docs_bzl/scenarios/reference_integration/score_platform/_expected/needs_json/needs.json`	Updates expected schema.
`src/tests/docs_bzl/scenarios/subdirectory_bundle/consumer/_expected/needs_json/needs.json`	Updates expected schema.
`src/tests/docs_bzl/scenarios/subdirectory_bundle/producer/_expected/needs_json/needs.json`	Updates expected schema.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

antonkri · 2026-09-21T08:40:02Z

+        valid_from = need.get("valid_from")
+        if valid_from:
+            try:
+                return _parse_version(valid_from) <= _parse_version(report_version)
+            except ValueError:
+                return False


Good catch, and you're right that it's inconsistent with the documented valid_from/valid_until semantics (tool_req__docs_req_attr_validity_correctness: "from" inclusive, "until" exclusive).

This is intentional scope for this PR, though: report_version here answers "everything relevant as of release X" (a snapshot of what should exist by then), not "everything still valid in release X" (which would additionally need the valid_until exclusion you describe). We deliberately kept it to the simpler valid_from-only check for the initial version of this feature - happy to open a follow-up to add report_version < valid_until support (with comp_req inheriting the full interval via derived_from, as you suggest) once there's a concrete need for it, rather than speculatively building it now.

Added focused unit tests for the current behavior (including the comp_req/derived_from inheritance path and malformed-value handling) in b71c770.

+    before.
+    """
+
+    def __call__(self, need: NeedItem, report_version: str | None) -> bool:


AlexanderLanin · 2026-09-21T08:28:38Z

    )
    app.config.needs_render_context.setdefault("linked_needs", _linked_needs_callable)
    app.config.needs_render_context.setdefault("needs_of_type", _needs_of_type_callable)
+    app.config.needs_render_context.setdefault("req_in_scope", _req_in_scope_callable)


req_in_scope does not really imply "version". Maybe "req_in_report_version"?

Good point, renamed to req_in_report_version in 0cd3801.

AlexanderLanin · 2026-09-21T08:31:21Z

    app.config.needs_render_context.setdefault("needs_of_type", _needs_of_type_callable)
+    app.config.needs_render_context.setdefault("req_in_scope", _req_in_scope_callable)
+    app.config.needs_render_context.setdefault(
+        "any_req_in_scope", _any_req_in_scope_callable


same here. Like any_req_in_report_version. Or something prettier.

Renamed to any_req_in_report_version in 0cd3801, thanks.

module_verification_report previously rendered both the module's own components AND every Feature reachable from those components, mixing module-scoped and platform-scoped statistics into a single report. - module_verification_report.need: drop the feature-loop section (Requirements/Architecture/Inspection Statistics per Feature). The report now covers Components only, as its name implies. - platform_verification_report.need (new): the feature-scoped counterpart, listing every Feature in the current build (via the existing needs_of_type("feat") helper) with the same statistics that were removed from the module report.

Adds an optional report_version attribute on document Needs. When set, module_verification_report and platform_verification_report only show requirements (and the Features/Components that own them) with valid_from <= report_version. comp_req has no valid_from of its own, so its scope is inherited from the feat_req it is derived_from. Features/Components with no in-scope requirement are dropped from the report entirely instead of rendering an empty section. Unset/empty report_version keeps reports unscoped, matching prior behavior.

- ruff-format src/extensions/score_sphinx_needs_templates/__init__.py (2 lines that now fit on one line each). - Regenerate the 13 checked-in _expected/needs_json + needs_local.json fixtures under src/tests/docs_bzl/scenarios to include the new report_version extra-option schema entry, matching what test_docs_bzl_scenario_expected_output already wrote locally when it detected the diff (CI fails this test on purpose after auto-updating, so the updated files can be reviewed and committed).

Adds focused unit tests for the report_version scoping helpers added in a previous commit, addressing a PR review finding that only the generated-schema fixtures exercised report_version, with no direct coverage of the filtering logic itself: - unscoped (no report_version) always includes everything - valid_from boundary is inclusive - malformed valid_from is excluded rather than raising - comp_req with no valid_from and nothing to inherit is excluded - comp_req inherits its scope from the feat_req it is derived_from - any_req_in_scope for empty/matching/non-matching requirement lists

Per review feedback: 'scope' didn't make clear these helpers are about report_version specifically. Renames the Jinja render-context globals and their backing classes/instances: - req_in_scope -> req_in_report_version (_RequirementInScope -> _RequirementInReportVersion) - any_req_in_scope -> any_req_in_report_version (_AnyRequirementInScope -> _AnyRequirementInReportVersion) Updates the two .need template call sites and the unit tests accordingly. No behavior change.

AlexanderLanin · 2026-09-21T22:02:26Z

LGTM, but I would like to merge #841 first

antonkri · 2026-09-22T06:57:06Z

#841

Hey @AlexanderLanin , why should #841 first? From my point of view there are no correlations.

AlexanderLanin · 2026-09-22T09:46:26Z

@copilot resolve the merge conflicts in this pull request. This PR adds report_version support to the templates.

MaximilianSoerenPollak

Some comments.

I think this is a good idea, just had some questions.

MaximilianSoerenPollak · 2026-09-22T09:38:17Z

+            except ValueError:
+                return False


In my opinion this can never happen, or am I thinking wrong?

I do like defensive programming, but this seems a bit weird.
If anything this defence may should be in the parser.

MaximilianSoerenPollak · 2026-09-22T09:39:32Z

+        return any(self(feat_req, report_version) for feat_req in linked_feat_reqs)
+
+
+_req_in_report_version_callable = _RequirementInReportVersion()


Single variable indirections are useless imo.
Makes it harder to read.

You are only using htem on 2 places, so this makes no sense to put into a variable that is also the same lenght...

…coping # Conflicts: # src/needs_templates/module_verification_report.need # src/needs_templates/platform_verification_report.need Co-authored-by: AlexanderLanin <5074553+AlexanderLanin@users.noreply.github.com>

Copilot · 2026-09-22T09:49:24Z

@copilot resolve the merge conflicts in this pull request. This PR adds report_version support to the templates.

Resolved by merging main into this branch and fixing the template conflicts in merge commit afe61f5.

antonkri requested review from AlexanderLanin, MaximilianSoerenPollak, a-zw, dcalavrezo-qorix and nradakovic as code owners September 21, 2026 06:56

github-project-automation Bot added this to INF - Infrastructure Community Sep 21, 2026

antonkri mentioned this pull request Sep 21, 2026

feat: platform_verification_report template #839

Merged

antonkri force-pushed the feat/split-platform-verification-report branch from 4a2ba64 to 11e4c89 Compare September 21, 2026 07:01

antonkri force-pushed the feat/report-version-scoping branch from 2e26aec to c565de1 Compare September 21, 2026 07:30

AlexanderLanin requested a balanced review from Copilot September 21, 2026 07:43

Copilot started reviewing on behalf of AlexanderLanin September 21, 2026 07:44 View session

Copilot AI reviewed Sep 21, 2026

View reviewed changes

AlexanderLanin reviewed Sep 21, 2026

View reviewed changes

antonkri force-pushed the feat/split-platform-verification-report branch from 11e4c89 to 3046110 Compare September 21, 2026 09:35

antonkri added 4 commits September 21, 2026 09:35

antonkri force-pushed the feat/report-version-scoping branch from 0cd3801 to 9c26357 Compare September 21, 2026 09:36

AlexanderLanin changed the base branch from feat/split-platform-verification-report to main September 21, 2026 22:02

Copilot started work on behalf of AlexanderLanin September 22, 2026 09:46 View session

MaximilianSoerenPollak reviewed Sep 22, 2026

View reviewed changes

Merge remote-tracking branch 'origin/main' into feat/report-version-s…

afe61f5

…coping # Conflicts: # src/needs_templates/module_verification_report.need # src/needs_templates/platform_verification_report.need Co-authored-by: AlexanderLanin <5074553+AlexanderLanin@users.noreply.github.com>

Copilot finished work on behalf of AlexanderLanin September 22, 2026 09:49

Copilot AI requested a review from AlexanderLanin September 22, 2026 09:49

Merge branch 'main' into feat/report-version-scoping

c5b79d2

AlexanderLanin approved these changes Sep 22, 2026

View reviewed changes

AlexanderLanin merged commit c65a0e8 into main Sep 22, 2026
25 checks passed

AlexanderLanin deleted the feat/report-version-scoping branch September 22, 2026 10:51

github-project-automation Bot moved this to Done in INF - Infrastructure Community Sep 22, 2026

		return any(self(feat_req, report_version) for feat_req in linked_feat_reqs)


		_req_in_report_version_callable = _RequirementInReportVersion()

Conversation

antonkri commented Sep 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why

What changed

Uh oh!

github-actions Bot commented Sep 21, 2026

Uh oh!

antonkri commented Sep 21, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

antonkri Sep 21, 2026

Choose a reason for hiding this comment

Uh oh!

AlexanderLanin Sep 21, 2026

Choose a reason for hiding this comment

Uh oh!

antonkri Sep 21, 2026

Choose a reason for hiding this comment

Uh oh!

AlexanderLanin Sep 21, 2026

Choose a reason for hiding this comment

Uh oh!

antonkri Sep 21, 2026

Choose a reason for hiding this comment

Uh oh!

AlexanderLanin commented Sep 21, 2026

Uh oh!

antonkri commented Sep 22, 2026

Uh oh!

AlexanderLanin commented Sep 22, 2026

Uh oh!

MaximilianSoerenPollak left a comment

Choose a reason for hiding this comment

Uh oh!

MaximilianSoerenPollak Sep 22, 2026

Choose a reason for hiding this comment

Uh oh!

MaximilianSoerenPollak Sep 22, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI commented Sep 22, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

antonkri commented Sep 21, 2026 •

edited

Loading