Add unit tests for x-tsdoc-tag support in node-core-library and heft-json-schema-typings-plugin.

Author: iclanton

heft-plugins/heft-json-schema-typings-plugin/package.json

@@ -12,7 +12,8 @@
   "scripts": {
     "build": "heft test --clean",
     "start": "heft build-watch",
-    "_phase:build": "heft run --only build -- --clean"
+    "_phase:build": "heft run --only build -- --clean",
+    "_phase:test": "heft run --only test -- --clean"
   },
   "peerDependencies": {
     "@rushstack/heft": "1.1.14"

heft-plugins/heft-json-schema-typings-plugin/src/JsonSchemaTypingsGenerator.ts

@@ -8,32 +8,9 @@ import { compileFromFile } from 'json-schema-to-typescript';
 
 import { type ITypingsGeneratorBaseOptions, TypingsGenerator } from '@rushstack/typings-generator';
 
-interface IJsonSchemaTypingsGeneratorBaseOptions extends ITypingsGeneratorBaseOptions {}
-
-/**
- * Adds a TSDoc release tag (e.g. `@public`, `@beta`) to all exported declarations
- * in generated typings.
- *
- * `json-schema-to-typescript` does not emit release tags, so this function
- * post-processes the output to ensure API Extractor treats these types with the
- * correct release tag when they are re-exported from package entry points.
- */
-function _addTsDocTagToExports(typingsData: string, tag: string): string {
-  // Normalize line endings for consistent regex matching.
-  // The TypingsGenerator base class applies NewlineKind.OsDefault when writing.
-  const normalized: string = typingsData.replace(/\r\n/g, '\n');
-
-  // Pass 1: For exports preceded by an existing JSDoc comment, insert
-  // the tag before the closing "*/".
-  let result: string = normalized.replace(/ \*\/\n(export )/g, ` *\n * ${tag}\n */\n$1`);
+import { _addTsDocTagToExports } from './TsDocTagHelpers';
 
-  // Pass 2: For exports NOT preceded by a JSDoc comment, insert a new
-  // JSDoc block. The negative lookbehind ensures Pass 1
-  // results are not double-matched.
-  result = result.replace(/(?<!\*\/\n)^(export )/gm, `/**\n * ${tag}\n */\n$1`);
-
-  return result;
-}
+interface IJsonSchemaTypingsGeneratorBaseOptions extends ITypingsGeneratorBaseOptions {}
 
 export class JsonSchemaTypingsGenerator extends TypingsGenerator {
   public constructor(options: IJsonSchemaTypingsGeneratorBaseOptions) {

heft-plugins/heft-json-schema-typings-plugin/src/TsDocTagHelpers.ts

@@ -0,0 +1,27 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+/**
+ * Adds a TSDoc release tag (e.g. `@public`, `@beta`) to all exported declarations
+ * in generated typings.
+ *
+ * `json-schema-to-typescript` does not emit release tags, so this function
+ * post-processes the output to ensure API Extractor treats these types with the
+ * correct release tag when they are re-exported from package entry points.
+ */
+export function _addTsDocTagToExports(typingsData: string, tag: string): string {
+  // Normalize line endings for consistent regex matching.
+  // The TypingsGenerator base class applies NewlineKind.OsDefault when writing.
+  const normalized: string = typingsData.replace(/\r\n/g, '\n');
+
+  // Pass 1: For exports preceded by an existing JSDoc comment, insert
+  // the tag before the closing "*/".
+  let result: string = normalized.replace(/ \*\/\n(export )/g, ` *\n * ${tag}\n */\n$1`);
+
+  // Pass 2: For exports NOT preceded by a JSDoc comment, insert a new
+  // JSDoc block. The negative lookbehind ensures Pass 1
+  // results are not double-matched.
+  result = result.replace(/(?<!\*\/\n)^(export )/gm, `/**\n * ${tag}\n */\n$1`);
+
+  return result;
+}

heft-plugins/heft-json-schema-typings-plugin/src/test/__snapshots__/TsDocTagHelpers.test.ts.snap

@@ -0,0 +1,61 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`_addTsDocTagToExports creates a new JSDoc block for an export without a preceding comment 1`] = `
+"/**
+ * @public
+ */
+export type Foo = {};"
+`;
+
+exports[`_addTsDocTagToExports does not double-tag an export that already has a JSDoc block 1`] = `
+"/**
+ * Already documented.
+ *
+ * @public
+ */
+export interface IConfig {
+  name: string;
+}"
+`;
+
+exports[`_addTsDocTagToExports does not modify non-export lines 1`] = `
+"// A leading comment
+const internal = 1;
+
+/**
+ * @beta
+ */
+export type Foo = {};"
+`;
+
+exports[`_addTsDocTagToExports handles multiple exports with and without JSDoc comments 1`] = `
+"/**
+ * First type.
+ *
+ * @beta
+ */
+export type Foo = {};
+
+/**
+ * @beta
+ */
+export type Bar = {};"
+`;
+
+exports[`_addTsDocTagToExports injects tag into an existing JSDoc comment before an export 1`] = `
+"/**
+ * A description.
+ *
+ * @beta
+ */
+export type Foo = {};"
+`;
+
+exports[`_addTsDocTagToExports normalizes CRLF line endings to LF 1`] = `
+"/**
+ * A description.
+ *
+ * @beta
+ */
+export type Foo = {};"
+`;

libraries/node-core-library/src/test/JsonSchema.test.ts

@@ -120,6 +120,23 @@ describe(JsonSchema.name, () => {
     });
   });
 
+  test('accepts a schema containing the x-tsdoc-tag custom keyword', () => {
+    const schemaWithTsDocTag: JsonSchema = JsonSchema.fromLoadedObject(
+      {
+        title: 'Test x-tsdoc-tag',
+        'x-tsdoc-tag': '@beta',
+        type: 'object',
+        properties: {
+          name: { type: 'string' }
+        },
+        additionalProperties: false,
+        required: ['name']
+      },
+      { schemaVersion: 'draft-07' }
+    );
+    expect(() => schemaWithTsDocTag.validateObject({ name: 'hello' }, '')).not.toThrow();
+  });
+
   test('successfully applies custom formats', () => {
     const schemaWithCustomFormat = JsonSchema.fromLoadedObject(
       {