[heft-json-schema-typings-plugin]/[node-core-library] Add x-tsdoc-release-tag support and improve compile() usage#5631
Merged
iclanton merged 14 commits intomicrosoft:mainfrom Feb 18, 2026
Merged
Conversation
…re-library. The plugin now reads the `x-tsdoc-tag` property from schema JSON files and injects the specified TSDoc release tag into generated `.d.ts` declarations. `JsonSchema` registers `x-tsdoc-tag` as a known AJV keyword so that strict mode validation does not reject schema files containing this property.
…json-schema-typings-plugin.
…d heft-json-schema-typings-plugin.
…emaTypingsGenerator - Replace compileFromFile with compile (reads file via TypingsGenerator base class) - Parse and strip x-tsdoc-tag from schema before passing to compile() - Pass format: false to skip prettier (avoids dynamic import issue in Jest) - Add jest.config.json with moduleNameMapper to stub prettier at load time - Add 3 snapshot tests: basic schema, x-tsdoc-tag injection, cross-file $ref - Add test fixture schemas in src/test/schemas/
- Add formatWithPrettier option to JsonSchemaTypingsGenerator constructor - Expose formatWithPrettier in the Heft plugin options and JSON schema - Defaults to false (skip prettier formatting)
iclanton
requested review from
apostolisms,
bmiddha,
dmichon-msft,
jxanthony and
octogonz
as code owners
octogonz
reviewed
Feb 18, 2026
heft-plugins/heft-json-schema-typings-plugin/src/test/schemas/with-tsdoc-tag.schema.json
Outdated
Show resolved
Hide resolved
octogonz
reviewed
Feb 18, 2026
common/changes/@rushstack/node-core-library/use-json-schema-plugin_2026-02-18-16-54.json
Outdated
Show resolved
Hide resolved
- Rename x-tsdoc-tag to x-tsdoc-release-tag across all files - Add X_TSDOC_RELEASE_TAG_KEYWORD constant exported from node-core-library - Move validation into TsDocReleaseTagHelpers.ts (renamed from TsDocTagHelpers.ts) - Validate that x-tsdoc-release-tag value is a single lowercase word starting with @ - Add unit tests for _validateTsDocReleaseTag - Update changelog messages
iclanton
changed the title
x-tsdoc-tag support and improve compile() usagex-tsdoc-release-tag support and improve compile() usage
octogonz
approved these changes
Feb 18, 2026
…ion support - Remove X_TSDOC_RELEASE_TAG_KEYWORD constant from node-core-library exports - Add allowVendorExtensionKeywords option (@beta) to IJsonSchemaLoadOptions - When enabled, recursively scans schema tree for x-<vendor>-<keyword> keys and registers them with AJV so strict mode does not reject them - Restore local X_TSDOC_RELEASE_TAG_KEY constant in heft-json-schema-typings-plugin - Update node-core-library changelog to describe the new option - Add tests for both enabled and disabled vendor extension behavior
- Rename allowVendorExtensionKeywords to rejectVendorExtensionKeywords - Vendor extensions (x-<vendor>-<keyword>) are now accepted by default - Set rejectVendorExtensionKeywords: true to restore strict behavior - Update tests and changelog accordingly
… extension support
- Add setup instructions with heft.json configuration example - Document all plugin options (srcFolder, generatedTsFolders, formatWithPrettier) - Document the x-tsdoc-release-tag vendor extension with usage example - Note that JsonSchema accepts vendor extensions by default
- Test that non-root vendor extension keywords are rejected - Test that malformed vendor tags (missing vendor segment, uppercase) are rejected
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
2 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.
Summary
Schema authors can now add an
"x-tsdoc-release-tag"custom property (e.g."x-tsdoc-release-tag": "@public") to their JSON schema files. The heft-json-schema-typings-plugin will read this property and inject the corresponding TSDoc release tag into all exported declarations in the generated.d.tsfiles, so that API Extractor applies the correct release level when these types are re-exported from package entry points.Additionally, the plugin now uses
compile()instead ofcompileFromFile()fromjson-schema-to-typescript, reading file contents through theTypingsGeneratorbase class. A newformatWithPrettieroption (defaulting tofalse) controls whether prettier formats the generated output. Cross-file$refresolution is fixed by passing the absolute schema directory ascwd.Details
@rushstack/heft-json-schema-typings-plugin:compileFromFile()tocompile(), lettingTypingsGeneratorhandle file I/O. This enables the plugin to parse the schema JSON first, strip the customx-tsdoc-release-tagproperty before passing it to the compiler, and inject the tag into the generated typings via post-processing.$refresolution by passingpath.dirname(filePath)(absolute path) ascwdtocompile(), instead of a relative dirname that resolved to an empty string for root-level schemas.formatWithPrettieroption (defaults tofalse) to the generator constructor, Heft plugin options, and the plugin's JSON schema. Whenfalse, prettier is skipped entirely, which also avoids adynamic import()crash in Jest VM sandboxes on Node 22+.moduleNameMapperstub forprettierinconfig/jest.config.jsonto prevent the module-load crash regardless of theformatsetting.@rushstack/node-core-library:x-tsdoc-release-tagas a custom AJV keyword inJsonSchemaso that strict mode validation does not reject schema files containing this property.How it was tested
JsonSchemaTypingsGenerator: basic schema generation,x-tsdoc-release-taginjection, and cross-file$refresolution betweenparent.schema.jsonandchild.schema.json._addTsDocTagToExportscovering: exports with existing JSDoc, exports without JSDoc, multiple exports, interface with properties, already-tagged exports, and multi-line JSDoc comments.x-tsdoc-release-tagAJV keyword registration innode-core-library.rush build --to @rushstack/heft-json-schema-typings-pluginandrush build --to heft-json-schema-typings-plugin-test— all tests pass.Impacted documentation
formatWithPrettierproperty.