You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Add optional --matrix-titles flag to include requirement titles in trace matrix - #223
Adds an optional --matrix-titles CLI flag that includes requirement titles
as a new Title column in the trace-matrix requirements table (right after ID). The flag is opt-in and defaults to off, so existing trace-matrix
output is unchanged unless explicitly requested.
Investigation (prototyping the Markdown → Pandoc → WeasyPrint PDF pipeline
with real content) found that normal prose titles wrap cleanly with no
template/CSS changes, but surfaced a pre-existing bug: long
underscore-joined test names in the Testing table (Test | Requirement | Passed | Failed) are unbreakable tokens that overflow the PDF page width,
silently pushing the Passed/Failed columns off the page today.
Both issues are fixed with a single technique: a new InsertSoftBreaks
helper inserts a zero-width space (U+200B) after every - and _ in
identifier-like text (requirement IDs, test names, and titles). This gives
the HTML renderer clean break points at identifier segment boundaries with no CSS/template changes and no page-count bloat (verified against
alternatives like table-layout: fixed, which nearly doubled page count,
and overflow-wrap: anywhere, which broke words at arbitrary mid-letter
positions and still added more pages than necessary).
Type of Change
Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
Documentation update
Code quality improvement
Related Issues
Closes #
Pre-Submission Checklist
Build and Test
Code builds successfully and all tests pass: pwsh ./build.ps1 — 1026 succeeded, 3 skipped (pre-existing, Unix-only), 0 failed
Code produces zero warnings
Code Quality
New code has appropriate XML documentation comments
Static analyzer warnings have been addressed
Quality Checks
All linters pass: pwsh ./lint.ps1 — YAML, markdown/spelling, SysML2/ReqStream/ReviewMark, dotnet format all clean
Testing
Added unit tests for new functionality
Updated existing tests if behavior changed
All tests follow the AAA (Arrange, Act, Assert) pattern
Test coverage is maintained or improved
Documentation
Updated README.md (if applicable) — not applicable
Updated docs/ documentation (if applicable) — design, verification, and user guide docs updated
Added code examples for new features (if applicable) — covered by --help text and user guide
Updated requirements.yaml (if applicable) — added ReqStream-Command-MatrixTitles and ReqStream-Report-TraceMatrixTitles, following the existing --matrix-depth convention
Additional Notes
Manually verified end-to-end through the real production pipeline (docs/requirements_report/definition.yaml → dotnet pandoc → dotnet weasyprint) using this repository's own requirements and a fresh test run. Rendered PDF pages confirm:
The Title column wraps cleanly within page width.
Semantic hyphenated requirement IDs (e.g. ReqStream-Cli-DepthInheritance) wrap at hyphen boundaries.
The previously-overflowing Testing table now fits fully on the page with all columns visible.
…ace matrix
Adds an opt-in Title column to the requirements table in the trace-matrix
export, enabled via a new --matrix-titles CLI flag (default off, preserving
existing output for all current callers).
Includes a zero-width-space insertion helper applied to identifier-like
text (requirement IDs, test names, and titles) that gives the Markdown-to-
HTML-to-PDF pipeline clean break opportunities after '-' and '_'. This also
fixes a pre-existing overflow bug where long underscore-joined test names in
the Testing table silently pushed the Passed/Failed columns off the PDF
page.
- New Requirement.Title column, dash-tuned for generous width allocation
- InsertSoftBreaks helper for identifier wrapping (no CSS/template changes needed)
- CLI flag, help text, and Context parsing for --matrix-titles
- Updated design/verification docs, user guide, and requirements.yaml entries
- Full test coverage for default/titled output, soft-break insertion, and CLI parsing
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Adds the optional --matrix-titles flag for including requirement titles in trace-matrix output, with identifier soft-break handling and updated tests and documentation.
Changes:
Adds CLI parsing and trace-matrix title-column support.
Updates tests, requirements, verification, design, and user documentation.
…ugfix
- README.md: add missing --matrix-titles line to the literal --help output block
- docs/design/reqstream.md: add --matrix-titles to the system-level CLI flag enumeration
- docs/design/reqstream/program.md: document that ProcessRequirements passes
context.MatrixTitles through to TraceMatrix.Export
- src/.../SelfTest/Validation.cs + docs/.../self-test/validation.md: document why
RunTraceMatrixTest strips U+200B zero-width-space characters before comparing
trace matrix content
- src/.../Tracing/TraceMatrix.cs: escape literal '|' characters in requirement
titles before inserting them into Markdown pipe-table cells, preventing a title
containing '|' from corrupting the generated trace matrix table; add a focused
unit test covering this case
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
includeTitles defaults to false, but this unconditionally changes every default Requirements export by inserting U+200B into IDs (the Testing path does the same below). That contradicts the stated opt-in/backward-compatible behavior and breaks byte/exact-text consumers; either gate the soft-break transformation behind an explicit option or revise the contract and tests to call out the format change.
This issue also appears on line 742 of the same file.
- Restore binary-compatible Export API: split the single 4-parameter
Export method into the original 3-parameter overload
(Export(filePath, depth, filterTags)) which delegates to a new
4-parameter overload (Export(filePath, depth, filterTags,
includeTitles)) containing the actual logic. This avoids breaking
already-compiled callers that invoke the pre-existing 3-parameter
signature.
- Document that InsertSoftBreaks is intentionally applied
unconditionally to requirement IDs and test names (independent of
includeTitles), fixing a pre-existing PDF table-overflow issue;
updated XML doc remarks and docs/design/reqstream/tracing/trace-matrix.md
accordingly so this is clearly a reviewed, intentional behavior.
- Add a Program-level test exercising the full --matrix-titles CLI
flag wiring end-to-end (Context.MatrixTitles -> Program.cs ->
TraceMatrix.Export), asserting the Title column appears in output.
- Fix EscapeTableCell to normalize embedded line breaks (\r\n, \r, \n)
to a single space so multi-line YAML titles cannot corrupt a
Markdown table row, with a regression test.
- Fix EscapeTableCell to escape backslashes before escaping pipes, so
a literal \| sequence in a title round-trips correctly, with a
regression test.
- Update companion verification/requirements docs to reflect the new
overload API, escaping contract, and added test coverage.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Requirement IDs are accepted as any nonblank scalar, so requirement.Id can legally contain |. Writing it raw here leaves that character as a Markdown column separator, making the Requirements table malformed for valid input; the new title path escapes the title but not the ID. Escape the ID as a table cell before adding soft breaks.
This issue also appears on line 803 of the same file.
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
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.
Pull Request
Description
Adds an optional
--matrix-titlesCLI flag that includes requirement titlesas a new
Titlecolumn in the trace-matrix requirements table (right afterID). The flag is opt-in and defaults to off, so existing trace-matrixoutput is unchanged unless explicitly requested.
Investigation (prototyping the Markdown → Pandoc → WeasyPrint PDF pipeline
with real content) found that normal prose titles wrap cleanly with no
template/CSS changes, but surfaced a pre-existing bug: long
underscore-joined test names in the Testing table (
Test | Requirement | Passed | Failed) are unbreakable tokens that overflow the PDF page width,silently pushing the
Passed/Failedcolumns off the page today.Both issues are fixed with a single technique: a new
InsertSoftBreakshelper inserts a zero-width space (U+200B) after every
-and_inidentifier-like text (requirement IDs, test names, and titles). This gives
the HTML renderer clean break points at identifier segment boundaries with
no CSS/template changes and no page-count bloat (verified against
alternatives like
table-layout: fixed, which nearly doubled page count,and
overflow-wrap: anywhere, which broke words at arbitrary mid-letterpositions and still added more pages than necessary).
Type of Change
Related Issues
Closes #
Pre-Submission Checklist
Build and Test
pwsh ./build.ps1— 1026 succeeded, 3 skipped (pre-existing, Unix-only), 0 failedCode Quality
Quality Checks
pwsh ./lint.ps1— YAML, markdown/spelling, SysML2/ReqStream/ReviewMark,dotnet formatall cleanTesting
Documentation
--helptext and user guideReqStream-Command-MatrixTitlesandReqStream-Report-TraceMatrixTitles, following the existing--matrix-depthconventionAdditional Notes
Manually verified end-to-end through the real production pipeline (
docs/requirements_report/definition.yaml→dotnet pandoc→dotnet weasyprint) using this repository's own requirements and a fresh test run. Rendered PDF pages confirm:Titlecolumn wraps cleanly within page width.ReqStream-Cli-DepthInheritance) wrap at hyphen boundaries.