Draft
Conversation
Contributor
❌MegaLinter analysis: Error
Detailed Issues❌ GHERKIN / gherkin-lint - 6 errors
|
Contributor
📦 Container Size AnalysisNote Comparing 📈 Size Comparison Table
|
Contributor
There was a problem hiding this comment.
Pull request overview
This PR expands the documentation generation system to produce additional SBDL-driven documents (software test specification and requirements traceability matrix) by unifying SBDL extraction from both Gherkin feature files and BATS integration tests, enabling traceability across requirements and tests.
Changes:
- Add a unified SBDL generator that combines Gherkin + BATS extraction for test-spec and traceability outputs.
- Introduce a BATS-to-SBDL converter and annotate existing BATS tests with
# bats test_tags=...for mapping. - Add new Pandoc-template documents (STS + RTM) and update the reusable workflow to generate/upload the new artifacts.
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
docs/support/generate-sbdl.py |
New unified Gherkin+BATS SBDL generation entrypoint used by workflows. |
docs/support/bats_sbdl_converter.py |
New converter to extract BATS @test cases and tag metadata for traceability. |
docs/support/gherkin_mapping_config.py |
Adds TEST_SPECIFICATION_CONFIG mapping for aspect→requirement→test hierarchy. |
docs/support/gherkin-to-sbdl.py |
Adds test-specification as a selectable conversion config. |
docs/support/gherkin_sbdl_converter.py |
Switches to slug IDs + emits custom:title and supports cross-type relations. |
docs/templates/software-test-specification.md.j2 |
New STS template rendering aspects/requirements/tests and untraced tests. |
docs/templates/requirements-traceability-matrix.md.j2 |
New RTM template mapping requirements to tests + coverage summary. |
docs/templates/software-requirements-specification.md.j2 |
Updates display logic to use hyphen IDs and custom:title. |
.github/workflows/wc-document-generation.yml |
Extends reusable workflow to generate STS/RTM (MD+PDF) for C++ and Rust and upload artifacts. |
test/cpp/integration-tests.bats |
Adds bats test_tags annotations for traceability mapping. |
test/rust/integration-tests.bats |
Adds bats test_tags annotations for traceability mapping. |
test/base/integration-tests.bats |
Adds bats test_tags annotation for traceability mapping. |
Comment on lines
2
to
3
| title: "Software test specification for amp-devcontainer | ||
| {%- if 'document-flavor' in sbdl %} ({{ sbdl['document-flavor']['custom:title'] }}){%- endif %}" |
There was a problem hiding this comment.
The YAML front-matter title is written as a multi-line double-quoted string (opening quote on the first line, closing quote on a later line). That’s not valid YAML for Pandoc front matter and will likely break PDF/MD generation. Use a YAML folded/block scalar (>-) or keep the title on a single line with the Jinja expression embedded without introducing a newline inside quoted text.
Suggested change
| title: "Software test specification for amp-devcontainer | |
| {%- if 'document-flavor' in sbdl %} ({{ sbdl['document-flavor']['custom:title'] }}){%- endif %}" | |
| title: >- | |
| Software test specification for amp-devcontainer{%- if 'document-flavor' in sbdl %} ({{ sbdl['document-flavor']['custom:title'] }}){%- endif %} |
Comment on lines
+2
to
+3
| title: "Requirements traceability matrix for amp-devcontainer | ||
| {%- if 'document-flavor' in sbdl %} ({{ sbdl['document-flavor']['custom:title'] }}){%- endif %}" |
There was a problem hiding this comment.
The YAML front-matter title is split across lines inside double quotes, which is invalid YAML and can cause Pandoc to fail parsing the metadata. Switch to a YAML block scalar (e.g. title: >-) or ensure the entire title (including the optional flavor suffix) is on one line without a multi-line quoted string.
Suggested change
| title: "Requirements traceability matrix for amp-devcontainer | |
| {%- if 'document-flavor' in sbdl %} ({{ sbdl['document-flavor']['custom:title'] }}){%- endif %}" | |
| title: >- | |
| Requirements traceability matrix for amp-devcontainer{%- if 'document-flavor' in sbdl %} ({{ sbdl['document-flavor']['custom:title'] }}){%- endif %} |
Comment on lines
+76
to
+84
| # Process Gherkin feature files | ||
| for feature_path in args.gherkin: | ||
| if os.path.isfile(feature_path): | ||
| print(f"Processing Gherkin: {feature_path}") | ||
| elements = gherkin_converter.extract_from_feature_file(feature_path) | ||
| gherkin_elements.extend(elements) | ||
| else: | ||
| print(f"File not found: {feature_path}", file=sys.stderr) | ||
|
|
There was a problem hiding this comment.
When a provided --gherkin / --bats path doesn’t exist (common when a glob doesn’t match), the script only prints an error and continues, ultimately exiting 0 and generating an incomplete SBDL/doc set. This will make CI appear green while silently dropping inputs. Consider tracking missing paths and exiting non-zero (or raising) if any inputs are missing.
docs/support/generate-sbdl.py
Outdated
Comment on lines
117
to
123
| _write_combined_sbdl(gherkin_converter, gherkin_elements, bats_converter, bats_tests, args.output, args.flavor) | ||
|
|
||
| total = len(gherkin_elements) + len(bats_tests) | ||
| print(f"Extracted {total} elements ({len(gherkin_elements)} from Gherkin, {len(bats_tests)} from BATS) to {args.output}") | ||
|
|
||
|
|
||
| def _write_combined_sbdl(gherkin_converter, gherkin_elements, bats_converter, bats_tests, output_file, flavor=""): |
There was a problem hiding this comment.
_write_combined_sbdl() takes gherkin_converter and bats_converter parameters but does not use gherkin_converter at all (and only uses bats_converter for a single helper call). This unused parameter makes the API harder to understand and suggests dead code; either remove the unused parameter(s) or use them for writing/escaping consistently.
Suggested change
| _write_combined_sbdl(gherkin_converter, gherkin_elements, bats_converter, bats_tests, args.output, args.flavor) | |
| total = len(gherkin_elements) + len(bats_tests) | |
| print(f"Extracted {total} elements ({len(gherkin_elements)} from Gherkin, {len(bats_tests)} from BATS) to {args.output}") | |
| def _write_combined_sbdl(gherkin_converter, gherkin_elements, bats_converter, bats_tests, output_file, flavor=""): | |
| _write_combined_sbdl(gherkin_elements, bats_converter, bats_tests, args.output, args.flavor) | |
| total = len(gherkin_elements) + len(bats_tests) | |
| print(f"Extracted {total} elements ({len(gherkin_elements)} from Gherkin, {len(bats_tests)} from BATS) to {args.output}") | |
| def _write_combined_sbdl(gherkin_elements, bats_converter, bats_tests, output_file, flavor=""): |
Comment on lines
+56
to
+64
| def __init__(self, requirement_tag_map: Optional[Dict[str, str]] = None): | ||
| """Initialize the converter. | ||
|
|
||
| Args: | ||
| requirement_tag_map: Optional mapping from tag names to requirement | ||
| identifiers (SBDL element IDs). When provided, tests with | ||
| matching tags will get a `requirement` relation in SBDL output. | ||
| """ | ||
| self.requirement_tag_map = requirement_tag_map or {} |
There was a problem hiding this comment.
requirement_tag_map is annotated as Optional[Dict[str, str]], but the converter actually supports tuple entries (identifier, type) (see _resolve_requirement_relations / _resolve_typed_relations). The current type hint and docstring are inconsistent with runtime behavior; update the annotation (e.g. to a Union[str, tuple[str, str]] value type) and adjust the docstring accordingly.
Contributor
📦 Container Size AnalysisNote Comparing 📈 Size Comparison Table
|
Contributor
📦 Container Size AnalysisNote Comparing 📈 Size Comparison Table
|
Ron (rjaegers)
temporarily deployed
to
acceptance-testing
GitHub Actions
Inactive
Contributor
Ron (rjaegers)
temporarily deployed
to
acceptance-testing
GitHub Actions
Inactive
|
Ron (rjaegers)
temporarily deployed
to
acceptance-testing
GitHub Actions
Inactive
Member
Author
ContextThis PR (branch
SBDL's strength is keeping definitions close to the code (see https://sbdl.dev). The goal is to embed SBDL declarations inline in the source files ( Requirements1. Add inline SBDL to Gherkin
|
Contributor
|
Ron (@rjaegers) I've opened a new pull request, #1172, to work on those changes. Once the pull request is ready, I'll request review from you. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
🚀 Hey, I have created a Pull Request
Description of changes
This pull request introduces a unified and extensible approach for generating SBDL (System Behavior Description Language) documents from both Gherkin feature files and BATS integration test files, enabling comprehensive requirements, test specification, and traceability document generation for both C++ and Rust codebases. The changes add new converters, configuration options, and workflow steps for automated document generation and artifact upload.
The most important changes are:
1. Unified SBDL Generation for Requirements and Test Specifications
generate-sbdl.py, which combines Gherkin and BATS parsing to generate SBDL files for both requirements and test specifications, supporting traceability between tests and requirements. This enables the generation of both requirements and test documents with traceability matrices for multiple flavors (C++ and Rust).2. BATS Test File Support and Traceability
bats_sbdl_converter.pyto extract BATS test cases, parse custom tags, and map them to requirements/aspects using a tag-based mapping. This facilitates linking BATS tests to requirements for traceability in generated documents.3. New Test Specification Configuration
TEST_SPECIFICATION_CONFIGingherkin_mapping_config.pyto map Gherkin Features to aspects, Rules to requirements, and Scenarios to tests, supporting the new test specification and traceability workflows.4. Improvements to Gherkin SBDL Conversion
gherkin_sbdl_converter.pyto use consistent slug-based identifiers, addcustom:titleattributes for display, and support cross-type SBDL relations (e.g., test→requirement, requirement→aspect) for improved traceability. [1] [2] [3] [4]5. Expanded Document Generation Workflow
.github/workflows/wc-document-generation.ymlto include new steps for generating C++ and Rust test specification and traceability documents (both Markdown and PDF), using the new scripts and configurations. Artifacts for all generated documents are uploaded for later use.Other Notable Changes
test-specificationas a valid config in bothgherkin-to-sbdl.pyand the newgenerate-sbdl.pyscript to support the new workflows.These changes provide a robust and extensible foundation for requirements management, test specification, and traceability across multiple languages and test frameworks.
✔️ Checklist