WIP: sphinx-needs filtering, Markdown & TRLC export rules (demo playground) by antonkri · Pull Request #615 · eclipse-score/docs-as-code

antonkri · 2026-06-24T10:47:54Z

⚠️ WIP — Demonstration purposes only. This PR is a playground/proof-of-concept and is not intended to be merged as-is.

What

Adds experimental Bazel rules and helper scripts around sphinx-needs to:

Filter needs.json output
Export sphinx-needs data to Markdown
Export sphinx-needs data to TRLC

Why

To demonstrate how requirements/needs data can be transformed into other formats (Markdown, TRLC) as part of the docs-as-code pipeline, for discussion and evaluation.

How to use

See the newly added README for details on the rules and scripts and example invocations.

Status

This is work in progress for demo only — APIs, naming, and structure are subject to change.

…round) Add Bazel macros and Python tools to post-process needs.json: - filter_needs_json / component_requirements / feature_requirements / assumptions_of_use: extract a subset of sphinx-needs elements - sphinx_needs_to_md: render needs as a Markdown document - sphinx_needs_to_trlc: convert S-CORE requirements to TRLC WIP / demonstration only.

github-actions · 2026-06-24T10:48:18Z

License Check Results

🚀 The license check job ran with the Bazel command:

bazel run --lockfile_mode=error //src:license-check

Status: ⚠️ Needs Review

Click to expand output

[License Check Output]
Extracting Bazel installation...
Starting local Bazel server (8.6.0) and connecting to it...
INFO: Invocation ID: 8ac129fd-4138-428a-a033-1db88c30eedf
Computing main repo mapping: 
Loading: 
Loading: 0 packages loaded
Loading: 0 packages loaded
Loading: 0 packages loaded
    currently loading: src
WARNING: Target pattern parsing failed.
ERROR: Skipping '//src:license-check': no such target '//src:license-check': target 'license-check' not declared in package 'src' defined by /home/runner/work/docs-as-code/docs-as-code/src/BUILD
ERROR: no such target '//src:license-check': target 'license-check' not declared in package 'src' defined by /home/runner/work/docs-as-code/docs-as-code/src/BUILD
INFO: Elapsed time: 5.570s
INFO: 0 processes.
ERROR: Build did NOT complete successfully
ERROR: Build failed. Not running target

+    )
+
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    with open(args.output, "w") as f:


+
+    args = parser.parse_args()
+
+    with open(args.input) as f:


+    document = render_document(data, title=args.title)
+
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    with open(args.output, "w") as f:


+    if not package or not (package[0].isalpha() or package[0] == "_"):
+        package = "Needs"
+
+    with open(args.input) as f:


github-actions · 2026-06-24T10:54:04Z

The created documentation from the pull request is available at: docu-html

Adds a 'req_chklst' sphinx-needs type that pins the reviewed state of build outputs via a SHA256 hash, plus a 'requirements_checklist' Bazel rule and 'validate_checklist.py' tool that recompute the hash over the validated target outputs and fail the build when it drifts.

antonkri · 2026-06-24T11:53:29Z

Added a separate commit: Requirement Checklist need type + validation rule (still WIP / demo only).

What this adds

New req_chklst sphinx-needs type (in metamodel.yaml) that pins the reviewed state of build outputs via a mandatory sha256 attribute, plus a targets attribute and a checklist link to the checklist document.
New requirements_checklist Bazel rule (docs.bzl) + validate_checklist.py tool: building the target recomputes the SHA256 over the validated dependency outputs (e.g. component_requirements) and fails the build if it differs from the hash recorded in the checklist need.

Workflow

bazel build //:<checklist_target> → fails on first run and prints the actual hash.
Review the checklist, paste the hash into the need's sha256.
Build passes until the validated requirements change again, then it fails and requests a re-review.

A demonstration of the consuming side (need element + requirements_checklist target) lives in the baselibs repo and is not part of this PR.

+
+    args = parser.parse_args()
+
+    with open(args.needs_json) as f:


- Add feature_architecture / component_architecture macros (no static/dynamic split) - Add architecture_checklist macro and arch_chklst need type - Report computed SHA256 on empty sha256 attribute in validate_checklist - Make req_chklst/arch_chklst sha256 optional so empty values build - Document new macros and need type

…ture checklists requirements_checklist and architecture_checklist now follow the sphinx-needs link graph recursively from the elements in deps and hash the whole closure, so a checklist goes out of date when an upstream dependency (e.g. a linked stakeholder requirement) changes, not only when a root element changes. - validate_checklist.py: add transitive mode via repeatable --link-field; follow links recursively, normalize version-constrained link targets (id[version==1] -> id), hash canonical serialization of the closure. - docs.bzl: add link_fields arg to both macros (defaults cover the requirement / architecture link chains); pass --link-field through. link_fields = [] restores the previous flat hashing. - metamodel.yaml + README_needs_rules.md: document the recursive behavior.

+
+    args = parser.parse_args()
+
+    with open(args.input) as f:


+        # whole closure (roots + all reachable dependencies).
+        root_needs: dict[str, dict[str, Any]] = {}
+        for path in args.inputs:
+            with open(path) as f:


+        # are invisible to the checklist.
+        all_needs: dict[str, dict[str, Any]] = {}
+        for extra_path in args.extra_needs_json:
+            with open(extra_path) as f:


…ound

…p_saf_fmea extraction

…s rule - score_module: replace comp_reqs with feat_arch sub-target - score_component: add comp_reqs and comp_arch sub-targets - Add trlc_to_sphinx_needs py_binary and script

+
+    args = parser.parse_args()
+
+    with open(args.input) as f:


+    document = render_document(data, title=args.title)
+
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    with open(args.output, "w") as f:


+
+    texts: list[str] = []
+    for path in args.inputs:
+        with open(path) as f:


+    data = convert(texts, project=args.project)
+
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    with open(args.output, "w") as f:


github-actions · 2026-08-24T00:16:21Z

Thanks for the pull request. This thread has been quiet for 30 days, so we are marking it as stale for now. Please take a quick look and let us know whether it is still up to date, still relevant, needs review, or is ready to merge. Any new activity will remove the stale label automatically. If nothing changes in the next 10 days, we will close it to keep the backlog current.

FScholPer and others added 5 commits June 23, 2026 10:00

first draft

063e357

Addded needs to requirements and added test

e9c48ce

fixed lint

9155fd6

Merge branch 'main' into template_inspection_needs

c401906

antonkri requested review from AlexanderLanin, MaximilianSoerenPollak, dcalavrezo-qorix and nradakovic as code owners June 24, 2026 10:47

github-project-automation Bot added this to INF - Infrastructure Community Jun 24, 2026

github-advanced-security Bot found potential problems Jun 24, 2026

View reviewed changes

github-advanced-security Bot found potential problems Jun 25, 2026

View reviewed changes

Comment thread scripts_bazel/validate_checklist.py Fixed

Comment thread scripts_bazel/validate_checklist.py Fixed

Comment thread scripts_bazel/validate_checklist.py Fixed

FScholPer added 2 commits June 25, 2026 07:03

removed overlapping test

60b3493

fix formatting

72bdbf9

antonkri force-pushed the ankr_rules_score_playground branch from e7c195e to b02108f Compare June 25, 2026 08:15

antonkri force-pushed the ankr_rules_score_playground branch from b02108f to 7c10704 Compare June 25, 2026 08:49

github-advanced-security Bot found potential problems Jun 26, 2026

View reviewed changes

Comment thread scripts_bazel/validate_checklist.py Fixed

Comment thread scripts_bazel/validate_checklist.py Fixed

Comment thread scripts_bazel/validate_checklist.py Fixed

Comment thread scripts_bazel/validate_checklist.py Fixed

Comment thread scripts_bazel/validate_checklist.py Fixed

antonkri force-pushed the ankr_rules_score_playground branch from 32e06cd to adf58f4 Compare June 26, 2026 14:15

github-advanced-security Bot found potential problems Jun 26, 2026

View reviewed changes

antonkri added 4 commits June 28, 2026 09:10

Merge branch 'template_inspection_needs' into ankr_rules_score_playgr…

5e201ef

…ound

docs: align verification evidence requirements and checklist rules

f49c22b

Add score_module and score_component macros

a91b52d

Add score_module/score_component bundling macros

6dcc1ea

docs: document sphinx-needs processing rules and add comp_saf_dfa/com…

c28a0b8

…p_saf_fmea extraction

antonkri force-pushed the ankr_rules_score_playground branch from 3f7e549 to c28a0b8 Compare June 30, 2026 13:38

Add feat_arch/comp_reqs/comp_arch sub-targets and trlc_to_sphinx_need…

5236966

…s rule - score_module: replace comp_reqs with feat_arch sub-target - score_component: add comp_reqs and comp_arch sub-targets - Add trlc_to_sphinx_needs py_binary and script

github-advanced-security Bot found potential problems Jul 24, 2026

View reviewed changes

github-actions Bot added the stale label Aug 24, 2026

Uh oh!

Conversation

antonkri commented Jun 24, 2026

What

Why

How to use

Status

Uh oh!

github-actions Bot commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

License Check Results

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jun 24, 2026

Uh oh!

antonkri commented Jun 24, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Aug 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions Bot commented Jun 24, 2026 •

edited

Loading