Updated structure, fixed glossary links, and migration to pkg:pypi/nide - #786
Open
sthagen wants to merge 7 commits into
Open
Updated structure, fixed glossary links, and migration to pkg:pypi/nide#786sthagen wants to merge 7 commits into
sthagen wants to merge 7 commits into
Conversation
…ion driven nide package Signed-off-by: Stefan Hagen <stefan@hagen.link>
…story Signed-off-by: Stefan Hagen <stefan@hagen.link>
- removed second hline before toc - fixed section nuimber in changes since last noting the new safety section - adjusted column widths for common objects table in pdf channel Signed-off-by: Stefan Hagen <stefan@hagen.link>
sthagen
marked this pull request as ready for review
July 7, 2026 22:28
Contributor
Author
|
Let us discuss this during our next meetin on 2026-07-09. |
adityasharad
reviewed
Jul 9, 2026
adityasharad
left a comment
adityasharad
left a comment
Contributor
There was a problem hiding this comment.
Live review from TC 2026-07-09
- in case we need footnotes these will actuallys work across formats (esp. the naviogation) - we can reduce the size of text in table cells and we can hint at columnwidths using a simple graphical like ruler argument to the columnwidths-directive - we can diff between render runs to expose the nature of changes also in binary files like PDF - we support the full dublin core attributes - we can run quality checks against OASIS rules from publication process (OASIS admins may update the rule file(s) - we only have a single frontmatter to manage - we are ten times as fast when rendering all artifacts - we now have a manifest file, checksum files for the PDF and embedded manifests - all manifests in text like formats use RFC8785 'Canonicalization Scheme (JCS)'' to prepare being able to sign them reproducibly - in case we want reproducible builds we can follow the SOURCE_DATE_EPOCH standard / convention as described in the documentation of nide and general examples per docs/SOURCE_DATE_EPOCH. Signed-off-by: Stefan Hagen <stefan@hagen.link>
Contributor
Author
|
@MColetta-OASIS I transformed the rules of your repository into data files in prose/edit/etc/ and those are validated by the nide engine. Hope you like it. Please also see oasis-tcs/dps#201 (comment) for the IMO bad change of replacing stages with versions on the frontpage that kind of sneaked in during the tumultuous year of 2025. |
Signed-off-by: Stefan Hagen <stefan@hagen.link>
Signed-off-by: Stefan Hagen <stefan@hagen.link>
Contributor
Author
|
Example run after the unicode version fix: ❯ make distclean release diff
2026-07-19T22:26:54.577655+00:00 INFO [nide._harvest]: first-authored-section = '# Scope'
2026-07-19T22:26:54.578018+00:00 INFO [nide._harvest]: track-examples = True
2026-07-19T22:26:54.578063+00:00 INFO [nide._harvest]: meta-example-global-number = 4321
2026-07-19T22:26:54.616803+00:00 INFO [nide._harvest]: Loaded 91 source files → 10751 lines total
2026-07-19T22:26:54.620252+00:00 INFO [nide._section]: Identified 564 relevant section headings
2026-07-19T22:26:54.620331+00:00 INFO [nide._section]: - 23 level-1 section heading(s)
2026-07-19T22:26:54.620350+00:00 INFO [nide._section]: - 93 level-2 section heading(s)
2026-07-19T22:26:54.620361+00:00 INFO [nide._section]: - 440 level-3 section heading(s)
2026-07-19T22:26:54.620371+00:00 INFO [nide._section]: - 8 level-4 section heading(s)
2026-07-19T22:26:54.620381+00:00 INFO [nide._section]: Section level nesting is valid.
2026-07-19T22:26:54.624243+00:00 INFO [nide._section]: Wrote 564 entries to section LUT files.
2026-07-19T22:26:54.625435+00:00 INFO [nide._example]: No example lines detected — generating only LUT stubs.
2026-07-19T22:26:54.638736+00:00 INFO [nide._harvest]: Embedding scan complete — 0 finding(s).
2026-07-19T22:26:55.111730+00:00 INFO [nide._assemble]: Loaded 91 source files → 10716 lines total (all channels)
2026-07-19T22:26:55.177404+00:00 INFO [nide._assemble]: IR written to build/ir.json (10418 nodes)
2026-07-19T22:26:55.643799+00:00 INFO [nide._channel]: Loaded IR from build/ir.json (10418 nodes)
2026-07-19T22:26:55.654238+00:00 INFO [nide._channel]: Rendered gfm-plus → build/gfm-plus.md (10717 lines)
Rendered markdown:
-rw-r--r--@ 1 ruth staff 690472 20 Jul 00:26 ../share/sarif-v2.2-draft.md
2026-07-19T22:26:56.118290+00:00 INFO [nide._channel]: Loaded IR from build/ir.json (10418 nodes)
2026-07-19T22:26:56.126940+00:00 INFO [nide._channel]: Rendered html → build/html.md (10517 lines)
2026-07-19T22:26:56.130254+00:00 INFO [nide._channel]: Section records → build/section-records.json
Rendered html:
-rw-r--r--@ 1 ruth staff 1503723 20 Jul 00:26 ../share/sarif-v2.2-draft.html
2026-07-19T22:26:59.042168+00:00 INFO [nide._assemble]: Loaded 91 source files → 10716 lines total (all channels)
2026-07-19T22:26:59.112096+00:00 INFO [nide._assemble]: IR written to build/ir.json (10418 nodes)
2026-07-19T22:26:59.579101+00:00 INFO [nide._channel]: Loaded IR from build/ir.json (10418 nodes)
2026-07-19T22:26:59.600346+00:00 WARNING [nide._channel]: build/typst.md line 10828: blind GFM table (no labeled caption) — typst figure counter slot consumed
2026-07-19T22:26:59.605421+00:00 INFO [nide._channel]: Rendered typst → build/typst.md (10741 lines)
2026-07-19T22:26:59.605611+00:00 INFO [nide._channel]: Lua filter → build/nide-columns.lua (pass to pandoc with --lua-filter)
nide manifest: written build/manifest.json
nide manifest: embedded block in build/gfm-plus.md
nide manifest: embedded block in build/html.md
nide manifest: embedded block in build/typst.md
nide validate: manifest self-hash OK
nide validate: source — 91 files: 91 OK, 0 CHANGED, 0 MISSING, 0 ADDED
nide validate: binder-hash OK
nide validate: source-state-hash OK
nide validate: outputs — 4 outputs: 4 OK, 0 CHANGED, 0 MISSING
nide validate: toolchain nide OK (2026.7.19+parent.3e973ada50)
nide validate: toolchain pandoc OK (3.10)
nide validate: toolchain typst OK (0.15.1 (unknown commit))
-rw-r--r--@ 1 ruth staff 1503723 20 Jul 00:26 ../share/sarif-v2.2-draft.html
-rw-r--r--@ 1 ruth staff 1695024 20 Jul 00:26 ../share/sarif-v2.2-draft.ir.json
-rw-r--r--@ 1 ruth staff 32299 20 Jul 00:27 ../share/sarif-v2.2-draft.manifest.json
-rw-r--r--@ 1 ruth staff 690472 20 Jul 00:26 ../share/sarif-v2.2-draft.md
-rw-r--r--@ 1 ruth staff 5092009 20 Jul 00:27 ../share/sarif-v2.2-draft.pdf
-rw-r--r-- 1 ruth staff 96 20 Jul 00:27 ../share/sarif-v2.2-draft.pdf.blake3
-rw-r--r-- 1 ruth staff 96 20 Jul 00:27 ../share/sarif-v2.2-draft.pdf.sha256
-rw-r--r--@ 1 ruth staff 661561 20 Jul 00:27 ../share/sarif-v2.2-draft.typ
--- HEAD:sarif-v2.2-draft.html
+++ ../share/sarif-v2.2-draft.html
@@ -8572,7 +8572,7 @@
<p><strong>[</strong><span id="RFC8089" class="anchor"></span><strong>RFC8089]</strong> Kerwin, M., "The "file" URI Scheme", RFC 8089, DOI 10.17487/RFC8089, February 2017, <a href="http://www.rfc-editor.org/info/rfc8089">http://www.rfc-editor.org/info/rfc8089</a>.</p>
<p><strong>[</strong><span id="RFC8259" class="anchor"></span><strong>RFC8259]</strong> Bray, T., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 8259, DOI 10.17487/RFC8259, December 2017, <a href="http://www.rfc-editor.org/info/rfc8259">http://www.rfc-editor.org/info/rfc8259</a>.</p>
<p><strong>[</strong><span id="SEMVER" class="anchor"></span><strong>SEMVER]</strong> "Semantic Versioning 2.0.0", <a href="http://semver.org/">http://semver.org/</a>.</p>
-<p><strong>[</strong><span id="UNICODE12" class="anchor"></span><strong>UNICODE12]</strong> Unicode 10.0, June 2017, <a href="http://www.unicode.org/versions/Unicode12.0.0">http://www.unicode.org/versions/Unicode12.0.0</a>.</p>
+<p><strong>[</strong><span id="UNICODE12" class="anchor"></span><strong>UNICODE12]</strong> Unicode 12.0, June 2017, <a href="http://www.unicode.org/versions/Unicode12.0.0">http://www.unicode.org/versions/Unicode12.0.0</a>.</p>
<h2 id="b2-informative-references-">B.2 Informative References <a id='informative-references'></a></h2>
<p>The following referenced documents are not required for the application of this document but may assist the reader with regard to a particular subject area.</p>
<p><strong>[</strong><span id="CMARK" class="anchor"></span><strong>CMARK]</strong> "CommonMark Spec", Version 0.28, (2017-08-01), <a href="http://spec.commonmark.org/0.28/">http://spec.commonmark.org/0.28/</a>.</p> |
Contributor
Author
|
Example run of the OASIS publication rules checker (per the nide engine and data provided by OASIS): ❯ make quality
nide quality: OASIS-SCOPE PASS Scope
nide quality: OASIS-CONFORMANCE PASS Conformance
nide quality: OASIS-TECHNICAL-COMMITTEE PASS Technical Committee
nide quality: OASIS-CHAIRS PASS Chairs
nide quality: OASIS-EDITORS PASS Editors
nide quality: OASIS-ABSTRACT PASS Abstract:
nide quality: OASIS-LOGO PASS 
nide quality: OASIS-RFC-2119-CITED PASS #RFC2119
nide quality: OASIS-RFC-8174-PAIRED PASS #RFC8174
nide quality: OASIS-RESID-TODO PASS 8807 item(s) checked
nide quality: OASIS-RESID-TBD PASS 8807 item(s) checked
nide quality: OASIS-RESID-FILL-IN PASS 8807 item(s) checked
nide quality: OASIS-LINK-DEAD-LISTS PASS 1193 item(s) checked
nide quality: OASIS-LINK-DOUBLE-SLASH PASS 1184 item(s) checked
nide quality: SARIF-TITLE PASS Static Analysis Results Interchange Format (SARIF) Version 2.2
nide quality: SARIF-STAGE-HEADING PASS Committee Specification Draft 01
nide quality: SARIF-THIS-VERSION PASS This version
nide quality: SARIF-LATEST-VERSION PASS Latest version
nide quality: SARIF-TC-LINK PASS https://docs.oasis-open.org/sarif/sarif/v2.2/csd01/sarif-v2.2-csd01.md (Authoritative) \
nide quality: SARIF-DOC-URL PASS https://docs.oasis-open.org/sarif/sarif/v2.2/csd01/sarif-v2.2-csd01.md (Authoritative) \
nide quality: SARIF-SAFETY-SECURITY PASS Safety, Security and Data Protection
nide quality: SARIF-REFERENCES-ANNEX PASS References
nide quality: SARIF-NORMATIVE-REFS PASS Normative References
nide quality: SARIF-INFORMATIVE-REFS PASS Informative References
nide quality: SARIF-LICENSE-ANNEX PASS License, Document Status, and Notices
nide quality: SARIF-ACKNOWLEDGMENTS PASS Acknowledgments
nide quality: SARIF-CHANGES-APPENDIX PASS Revision History
nide quality: SARIF-KEY-WORDS-SECTION PASS Key Words
nide quality: SARIF-DEFINITIONS-SECTION PASS Definitions and Acronyms
nide quality: 0 blocker(s) 0 warning(s) 29 pass(es) 0 N/A |
Signed-off-by: Stefan Hagen <stefan@hagen.link>
11 tasks
|
From the publication-process quality side, this is in good shape. The two-file rules split works well, and SARIF-THIS-VERSION / SARIF-LATEST-VERSION are permitted under Naming Directives Sec 6.2, which allows "version" while discouraging it, so nothing here blocks. Moving those and the headings they check to Stage is a recommendation, not a requirement, and would line SARIF up with CSAF. Your call as editor. One implementation note while we're in the rules files: these rules key each rule off |
davidmalcolm
approved these changes
Aug 7, 2026
davidmalcolm
left a comment
davidmalcolm
left a comment
Contributor
There was a problem hiding this comment.
I took a brief look through this; seems correct.
davidmalcolm
reviewed
Aug 7, 2026
| This information is given for the convenience of users of this document and does not constitute an endorsement by OASIS of any of the products named. Equivalent products may be used if they can be shown to lead to the same results. | ||
|
|
||
| ## Changes From the Previous Version | ||
| ## Changes From the Previous Version 2.1 |
Contributor
There was a problem hiding this comment.
I'd have put the 2.1 in parentheses here (presumably would also affect the .json file above)
davidmalcolm
reviewed
Aug 7, 2026
| | `sarif-v2.2-draft.pdf` | PDF | | ||
| | `sarif-v2.2-draft.pdf.sha256` | SHA-256 checksum of the PDF | | ||
| | `sarif-v2.2-draft.pdf.blake3` | BLAKE3 checksum of the PDF | | ||
| | `sarif-v2.2-draft.typ` | Typst source (input used to produce the PDF) | |
Contributor
There was a problem hiding this comment.
Maybe clarify as "Generated Typst source (input used to produce the PDF) "
adityasharad
reviewed
Aug 7, 2026
adityasharad
left a comment
adityasharad
left a comment
Contributor
There was a problem hiding this comment.
Markdown source, readmes, and tool structure look good. One comment that we might have merge conflicts from recent edits.
| > | ||
| > Prohibited term used in para\[0\]\\spans\[2\]. | ||
|
|
||
| Literal square brackets and backslashes anywhere else in a plain text message **MAY** be written either without escaping, or escaped with a backslash (`"\"`). However, if a sequence of literal characters in a plain text message could be parsed as an embedded link, a SARIF producer **SHOULD** escape the literal square brackets with a backslash (`"\"`) to avoid ambiguity. |
Contributor
There was a problem hiding this comment.
Merge conflict resolved the opposite way?
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
4 participants
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.
Editorial and Tool Changes
While this PR is not merged, you can view the rendered documents in https://github.com/oasis-tcs/sarif-spec/tree/updated-template-and-navigation-fixes/sarif-2.2/prose/share