feat: schema generation by gennaroprota · Pull Request #1178 · cppalliance/mrdocs

gennaroprota · 2026-04-16T15:07:10Z

This PR addes a --schemas[=<dir>] option that generates a mrdocs-dom-schema.json (Handlebars DOM) and mrdocs.rnc (XML output). Both schemas are generated from the reflection metadata. The old, hand-written, mrdocs.rnc is replaced entirely in CI.

github-actions · 2026-04-16T15:07:34Z

🚧 Danger.js checks for MrDocs are experimental; expect some rough edges while we tune the rules.

✨ Highlights

🧪 Existing golden tests changed (behavior likely shifted)

🧾 Changes by Scope

Scope	Lines Δ%	Lines Δ	Lines +	Lines -	Files Δ	Files +	Files ~	Files ↔	Files -
🛠️ Source	45%	2600	2444	156	20	4	16	-	-
🥇 Golden Tests	32%	1853	1672	181	169	-	169	-	-
🏗️ Build	17%	964	11	953	2	-	1	-	1
🧪 Unit Tests	6%	326	326	-	1	1	-	-	-
🔧 Toolchain	<1%	12	10	2	2	-	2	-	-
🔧 Toolchain Tests	<1%	2	1	1	1	-	1	-	-
Total	100%	5757	4464	1293	195	5	189	-	1

Legend: Files + (added), Files ~ (modified), Files ↔ (renamed), Files - (removed)

🔝 Top Files

mrdocs.rnc (Build): 949 lines Δ (+0 / -949)
include/mrdocs/Schemas/RncSchemaWriter.hpp (Source): 837 lines Δ (+837 / -0)
include/mrdocs/Schemas/DomDescriptions.hpp (Source): 761 lines Δ (+761 / -0)

Generated by 🚫 dangerJS against 7c86fab

codecov · 2026-04-16T15:08:19Z

Codecov Report

❌ Patch coverage is 96.77419% with 11 lines in your changes missing coverage. Please review.
✅ Project coverage is 79.07%. Comparing base (0246935) to head (b9fac7c).

Files with missing lines	Patch %	Lines
src/lib/Gen/xml/XMLWriter.cpp	18.18%	9 Missing ⚠️
include/mrdocs/Schemas/DomSchemaWriter.hpp	98.84%	0 Missing and 2 partials ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #1178      +/-   ##
===========================================
+ Coverage    78.85%   79.07%   +0.21%     
===========================================
  Files          308      306       -2     
  Lines        32157    32460     +303     
  Branches      6456     6441      -15     
===========================================
+ Hits         25359    25667     +308     
- Misses        4436     4438       +2     
+ Partials      2362     2355       -7

Flag	Coverage Δ
bootstrap	`81.90% <100.00%> (+<0.01%)`	⬆️
cpp	`78.78% <96.75%> (+0.23%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

cppalliance-bot · 2026-04-16T15:14:09Z

An automated preview of the documentation is available at https://1178.mrdocs.prtest2.cppalliance.org/index.html

If more commits are pushed to the pull request, the docs will rebuild at the same URL.

2026-05-01 14:49:11 UTC

Add a --schemas[=<dir>] option that writes a JSON Schema file (mrdocs-dom-schema.json) describing every object and field available to Handlebars templates. The schema is derived from the same compile-time reflection metadata used by MapReflectedType.hpp, so it stays in sync with the code automatically. The option requires no config file or source files — it writes the schema and exits immediately.

OperatorKind was the only enum serialized as a raw integer. All other enums serialize as human-readable strings. Change tag_invoke to use getOperatorName, consistent with the rest.

--schemas now writes both mrdocs-dom-schema.json (Handlebars DOM) and mrdocs.rnc (XML output). The XML schema mirrors XMLWriter.cpp's serialization.

…ClassKind Replace manual toString and tag_invoke overloads with MRDOCS_DESCRIBE_ENUM for four enums whose kebab-case names match the existing string representations. The XML writer now emits these fields (e.g. <access>public</access>, <constexpr>constexpr</constexpr>) where they were previously silently skipped. None/none sentinel values are suppressed via a generic has_none_enumerator check. TypeKind stays manual because toKebabCase("LValueReference") produces "l-value-reference", not the established "lvalue-reference".

… --schemas This guarantees the RELAX NG schema stays in sync with the C++ type definitions. Every CI run now validates all golden test XML files against a schema derived from the same reflection metadata that produces the XML.

alandefreitas · 2026-04-21T05:49:58Z

:)

gennaroprota · 2026-04-21T08:38:08Z

Path coverage is OK, isn't it? I added the PR description.

This adds a small lookup table keyed by (typeName, memberName) carrying hand-written descriptions for the DOM seen by Handlebars templates which become "description" fields in the JSON schema.

alandefreitas

What about documentation? How do I use the feature? What about the schema in the documentation? Do we have no schema files in the repository? How do we check if the files are up to date in CI? Some of the changes in the golden files are also kind of weird (like ids changing and things like that and some groups are just empty, which could probably be removed in the schema - I'm not sure).

The PR is great though. The only reason I left many comment is because the PR is huge. 😅

alandefreitas · 2026-05-01T23:52:18Z

+*/
+inline
+std::string
+toJson(dom::Value const& v, int indent = 0)


Don't we already have this functionality defined somewhere else in the Dom library?

alandefreitas · 2026-05-01T23:54:00Z

+*/
+inline
+std::string
+toJson(dom::Value const& v, int indent = 0)


Why is this file in Schemas if it's a general JSON emitter (not JSON schema emitter)?

alandefreitas · 2026-05-01T23:56:30Z

+*/
+inline
+std::string
+toJson(dom::Value const& v, int indent = 0)


Why would the JSON schema go through dom::Value anyway?

alandefreitas · 2026-05-01T23:57:51Z

@@ -0,0 +1,761 @@
+//


I don't think we need public mrdocs/Schemas at all. Each generator (or category of generator) has an associated schema (or not). If even the generators aren't public, I see no reason for the scheme logic to be public.

alandefreitas · 2026-05-01T23:59:31Z

+            return entry.text;
+        }
+    }
+    return {};


How do we ensure we never get here?

alandefreitas · 2026-05-02T00:00:06Z

+/** Build the complete DOM JSON Schema document.
+*/
+inline dom::Value
+buildDomSchema()


DOM Schema means JSON schema?

alandefreitas · 2026-05-02T00:01:35Z

+        // -------------------------------------------------------
+        // Header
+        // -------------------------------------------------------
+        line("#");


This main function is kind of hard for a human to read. Is this one of these cases where instead of using reflection to improve the schema, we make the function very complex to match the bad pattern we used to have before?

alandefreitas · 2026-05-02T00:04:17Z

+    output, suitable for writing directly to `mrdocs.rnc`.
+*/
+inline std::string
+buildRncSchema()


Should we be using RNC for XML at all? If we have reflection, why not already output the final schema?

alandefreitas · 2026-05-02T00:06:22Z

+        properties.set("class", withDesc(std::move(classSchema), "class"));
+
+        dom::Object boolSchema;
+        boolSchema.set("type", "boolean");


No reflection?

alandefreitas · 2026-05-02T00:06:58Z

+
+} // (anon)
+
+TEST_SUITE(


No tests for the other ones?

gennaroprota changed the title ~~Feat/schema generation~~ feat: schema generation Apr 17, 2026

gennaroprota force-pushed the feat/schema_generation branch 5 times, most recently from 762bc4d to cdda298 Compare April 17, 2026 16:10

gennaroprota added 5 commits April 17, 2026 18:31

fix: serialize OperatorKind as a string in the DOM

857a310

OperatorKind was the only enum serialized as a raw integer. All other enums serialize as human-readable strings. Change tag_invoke to use getOperatorName, consistent with the rest.

feat: have --schemas also generate an XML schema

4f5abd0

--schemas now writes both mrdocs-dom-schema.json (Handlebars DOM) and mrdocs.rnc (XML output). The XML schema mirrors XMLWriter.cpp's serialization.

gennaroprota force-pushed the feat/schema_generation branch from cdda298 to b9fac7c Compare April 17, 2026 16:31

feat(schemas): describe DOM types and members in the JSON schema

7c86fab

This adds a small lookup table keyed by (typeName, memberName) carrying hand-written descriptions for the DOM seen by Handlebars templates which become "description" fields in the JSON schema.

alandefreitas reviewed May 2, 2026

View reviewed changes


		} // (anon)

		TEST_SUITE(

Conversation

gennaroprota commented Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

Uh oh!

✨ Highlights

🧾 Changes by Scope

🔝 Top Files

Uh oh!

codecov Bot commented Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

cppalliance-bot commented Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

alandefreitas commented Apr 21, 2026

Uh oh!

gennaroprota commented Apr 21, 2026

Uh oh!

alandefreitas left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

gennaroprota commented Apr 16, 2026 •

edited

Loading

github-actions Bot commented Apr 16, 2026 •

edited

Loading

codecov Bot commented Apr 16, 2026 •

edited

Loading

cppalliance-bot commented Apr 16, 2026 •

edited

Loading