[heft-json-schema-typings-plugin] Add snapshot unit tests for JsonSchemaTypingsGenerator

- 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/

Author: iclanton

heft-plugins/heft-json-schema-typings-plugin/config/jest.config.json

@@ -0,0 +1,6 @@
+{
+  "extends": "local-node-rig/profiles/default/config/jest.config.json",
+  "moduleNameMapper": {
+    "^prettier$": "<configDir>/jestMocks/prettier.js"
+  }
+}

heft-plugins/heft-json-schema-typings-plugin/config/jestMocks/prettier.js

@@ -0,0 +1,6 @@
+// Stub for prettier.  json-schema-to-typescript eagerly require('prettier') at
+// module load time.  Prettier v3's CJS entry does a top-level dynamic import()
+// which crashes inside Jest's VM sandbox on Node 22+.  Since compile() is called
+// with format: false, prettier is never invoked — this stub just prevents the
+// module-load crash.
+module.exports = {};

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

@@ -1,40 +1,58 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
-import { readFile } from 'node:fs/promises';
-import path from 'node:path';
+import * as path from 'node:path';
 
-import { compileFromFile } from 'json-schema-to-typescript';
+import { compile } from 'json-schema-to-typescript';
 
 import { type ITypingsGeneratorBaseOptions, TypingsGenerator } from '@rushstack/typings-generator';
 
 import { _addTsDocTagToExports } from './TsDocTagHelpers';
 
 interface IJsonSchemaTypingsGeneratorBaseOptions extends ITypingsGeneratorBaseOptions {}
 
+const SCHEMA_FILE_EXTENSION: '.schema.json' = '.schema.json';
+const X_TSDOC_TAG_KEY: 'x-tsdoc-tag' = 'x-tsdoc-tag';
+
+type Json4Schema = Parameters<typeof compile>[0];
+interface IExtendedJson4Schema extends Json4Schema {
+  [X_TSDOC_TAG_KEY]?: string;
+}
+
 export class JsonSchemaTypingsGenerator extends TypingsGenerator {
   public constructor(options: IJsonSchemaTypingsGeneratorBaseOptions) {
     super({
       ...options,
-      fileExtensions: ['.schema.json'],
-      // Don't bother reading the file contents, compileFromFile will read the file
-      readFile: () => '',
+      fileExtensions: [SCHEMA_FILE_EXTENSION],
       // eslint-disable-next-line @typescript-eslint/naming-convention
-      parseAndGenerateTypings: async (fileContents: string, filePath: string): Promise<string> => {
-        const typings: string = await compileFromFile(filePath, {
+      parseAndGenerateTypings: async (
+        fileContents: string,
+        filePath: string,
+        relativePath: string
+      ): Promise<string> => {
+        const parsedFileContents: IExtendedJson4Schema = JSON.parse(fileContents);
+        const { [X_TSDOC_TAG_KEY]: tsdocTag, ...jsonSchemaWithoutTsDocTag } = parsedFileContents;
+
+        // Use the absolute directory of the schema file so that cross-file $ref
+        // (e.g. { "$ref": "./other.schema.json" }) resolves correctly.
+        const dirname: string = path.dirname(filePath);
+        const filenameWithoutExtension: string = filePath.slice(
+          dirname.length + 1,
+          -SCHEMA_FILE_EXTENSION.length
+        );
+        let typings: string = await compile(jsonSchemaWithoutTsDocTag, filenameWithoutExtension, {
           // The typings generator adds its own banner comment
           bannerComment: '',
-          cwd: path.dirname(filePath)
+          cwd: dirname,
+          // The generated typings are machine-produced .d.ts files that do not need
+          // prettier formatting.
+          format: false
         });
 
         // Check for an "x-tsdoc-tag" property in the schema (e.g. "@public" or "@beta").
         // If present, inject the tag into JSDoc comments for all exported declarations.
-        const schemaContent: string = await readFile(filePath, 'utf-8');
-        const schemaJson: { 'x-tsdoc-tag'?: string } = JSON.parse(schemaContent);
-        const tsdocTag: string | undefined = schemaJson['x-tsdoc-tag'];
-
         if (tsdocTag) {
-          return _addTsDocTagToExports(typings, tsdocTag);
+          typings = _addTsDocTagToExports(typings, tsdocTag);
         }
 
         return typings;

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

@@ -0,0 +1,63 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import { FileSystem, PackageJsonLookup } from '@rushstack/node-core-library';
+
+import { JsonSchemaTypingsGenerator } from '../JsonSchemaTypingsGenerator';
+
+const projectFolder: string = PackageJsonLookup.instance.tryGetPackageFolderFor(__dirname)!;
+const schemasFolder: string = `${__dirname}/schemas`;
+const outputFolder: string = `${projectFolder}/temp/test-typings-output`;
+
+async function readGeneratedTypings(schemaRelativePath: string): Promise<string> {
+  const outputPath: string = `${outputFolder}/${schemaRelativePath}.d.ts`;
+  return await FileSystem.readFileAsync(outputPath);
+}
+
+describe('JsonSchemaTypingsGenerator', () => {
+  beforeEach(async () => {
+    await FileSystem.ensureEmptyFolderAsync(outputFolder);
+  });
+
+  it('generates typings for a basic object schema', async () => {
+    const generator = new JsonSchemaTypingsGenerator({
+      srcFolder: schemasFolder,
+      generatedTsFolder: outputFolder
+    });
+
+    await generator.generateTypingsAsync(['basic.schema.json']);
+    const typings: string = await readGeneratedTypings('basic.schema.json');
+    expect(typings).toMatchSnapshot();
+  });
+
+  it('injects x-tsdoc-tag into exported declarations', async () => {
+    const generator = new JsonSchemaTypingsGenerator({
+      srcFolder: schemasFolder,
+      generatedTsFolder: outputFolder
+    });
+
+    await generator.generateTypingsAsync(['with-tsdoc-tag.schema.json']);
+    const typings: string = await readGeneratedTypings('with-tsdoc-tag.schema.json');
+    expect(typings).toMatchSnapshot();
+    expect(typings).toContain('@public');
+  });
+
+  it('resolves cross-file $ref between schema files', async () => {
+    const generator = new JsonSchemaTypingsGenerator({
+      srcFolder: schemasFolder,
+      generatedTsFolder: outputFolder
+    });
+
+    await generator.generateTypingsAsync(['child.schema.json', 'parent.schema.json']);
+    const [parentTypings, childTypings]: string[] = await Promise.all([
+      readGeneratedTypings('parent.schema.json'),
+      readGeneratedTypings('child.schema.json')
+    ]);
+
+    expect(childTypings).toMatchSnapshot('child output');
+    expect(parentTypings).toMatchSnapshot('parent output');
+
+    // The parent typings should reference the child type
+    expect(parentTypings).toContain('ChildType');
+  });
+});

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

@@ -0,0 +1,85 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`JsonSchemaTypingsGenerator generates typings for a basic object schema 1`] = `
+"// This file was generated by a tool. Modifying it will produce unexpected behavior
+
+export interface BasicConfig {
+/**
+ * The name of the item.
+ */
+name: string
+/**
+ * The number of items.
+ */
+count?: number
+/**
+ * Whether the feature is enabled.
+ */
+enabled?: boolean
+}
+"
+`;
+
+exports[`JsonSchemaTypingsGenerator injects x-tsdoc-tag into exported declarations 1`] = `
+"// This file was generated by a tool. Modifying it will produce unexpected behavior
+
+/**
+ * @public
+ */
+export interface PublicConfig {
+/**
+ * A value.
+ */
+value?: string
+}
+"
+`;
+
+exports[`JsonSchemaTypingsGenerator resolves cross-file $ref between schema files: child output 1`] = `
+"// This file was generated by a tool. Modifying it will produce unexpected behavior
+
+/**
+ * A reusable child type.
+ */
+export interface ChildType {
+/**
+ * The name of the child.
+ */
+childName: string
+/**
+ * The value of the child.
+ */
+childValue?: number
+}
+"
+`;
+
+exports[`JsonSchemaTypingsGenerator resolves cross-file $ref between schema files: parent output 1`] = `
+"// This file was generated by a tool. Modifying it will produce unexpected behavior
+
+export interface ParentConfig {
+/**
+ * A label for the parent.
+ */
+label: string
+child: ChildType
+/**
+ * A list of children.
+ */
+children?: ChildType[]
+}
+/**
+ * A reusable child type.
+ */
+export interface ChildType {
+/**
+ * The name of the child.
+ */
+childName: string
+/**
+ * The value of the child.
+ */
+childValue?: number
+}
+"
+`;

heft-plugins/heft-json-schema-typings-plugin/src/test/schemas/basic.schema.json

@@ -0,0 +1,20 @@
+{
+  "title": "Basic Config",
+  "type": "object",
+  "properties": {
+    "name": {
+      "description": "The name of the item.",
+      "type": "string"
+    },
+    "count": {
+      "description": "The number of items.",
+      "type": "integer"
+    },
+    "enabled": {
+      "description": "Whether the feature is enabled.",
+      "type": "boolean"
+    }
+  },
+  "additionalProperties": false,
+  "required": ["name"]
+}

heft-plugins/heft-json-schema-typings-plugin/src/test/schemas/child.schema.json

@@ -0,0 +1,17 @@
+{
+  "title": "Child Type",
+  "description": "A reusable child type.",
+  "type": "object",
+  "properties": {
+    "childName": {
+      "description": "The name of the child.",
+      "type": "string"
+    },
+    "childValue": {
+      "description": "The value of the child.",
+      "type": "number"
+    }
+  },
+  "additionalProperties": false,
+  "required": ["childName"]
+}

heft-plugins/heft-json-schema-typings-plugin/src/test/schemas/parent.schema.json

@@ -0,0 +1,22 @@
+{
+  "title": "Parent Config",
+  "type": "object",
+  "properties": {
+    "label": {
+      "description": "A label for the parent.",
+      "type": "string"
+    },
+    "child": {
+      "$ref": "./child.schema.json"
+    },
+    "children": {
+      "description": "A list of children.",
+      "type": "array",
+      "items": {
+        "$ref": "./child.schema.json"
+      }
+    }
+  },
+  "additionalProperties": false,
+  "required": ["label", "child"]
+}

heft-plugins/heft-json-schema-typings-plugin/src/test/schemas/with-tsdoc-tag.schema.json

@@ -0,0 +1,12 @@
+{
+  "x-tsdoc-tag": "@public",
+  "title": "Public Config",
+  "type": "object",
+  "properties": {
+    "value": {
+      "description": "A value.",
+      "type": "string"
+    }
+  },
+  "additionalProperties": false
+}