[heft-json-schema-typings-plugin] Implementation of a Heft plugin that generates TypeScript typings from JSON schemata.

README.md

@@ -67,6 +67,7 @@ These GitHub repositories provide supplementary resources for Rush Stack:
 | [/heft-plugins/heft-dev-cert-plugin](./heft-plugins/heft-dev-cert-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fheft-dev-cert-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Fheft-dev-cert-plugin) | [changelog](./heft-plugins/heft-dev-cert-plugin/CHANGELOG.md) | [@rushstack/heft-dev-cert-plugin](https://www.npmjs.com/package/@rushstack/heft-dev-cert-plugin) |
 | [/heft-plugins/heft-isolated-typescript-transpile-plugin](./heft-plugins/heft-isolated-typescript-transpile-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fheft-isolated-typescript-transpile-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Fheft-isolated-typescript-transpile-plugin) | [changelog](./heft-plugins/heft-isolated-typescript-transpile-plugin/CHANGELOG.md) | [@rushstack/heft-isolated-typescript-transpile-plugin](https://www.npmjs.com/package/@rushstack/heft-isolated-typescript-transpile-plugin) |
 | [/heft-plugins/heft-jest-plugin](./heft-plugins/heft-jest-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fheft-jest-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Fheft-jest-plugin) | [changelog](./heft-plugins/heft-jest-plugin/CHANGELOG.md) | [@rushstack/heft-jest-plugin](https://www.npmjs.com/package/@rushstack/heft-jest-plugin) |
+| [/heft-plugins/heft-json-schema-typings-plugin](./heft-plugins/heft-json-schema-typings-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fheft-json-schema-typings-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Fheft-json-schema-typings-plugin) | [changelog](./heft-plugins/heft-json-schema-typings-plugin/CHANGELOG.md) | [@rushstack/heft-json-schema-typings-plugin](https://www.npmjs.com/package/@rushstack/heft-json-schema-typings-plugin) |
 | [/heft-plugins/heft-lint-plugin](./heft-plugins/heft-lint-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fheft-lint-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Fheft-lint-plugin) | [changelog](./heft-plugins/heft-lint-plugin/CHANGELOG.md) | [@rushstack/heft-lint-plugin](https://www.npmjs.com/package/@rushstack/heft-lint-plugin) |
 | [/heft-plugins/heft-localization-typings-plugin](./heft-plugins/heft-localization-typings-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fheft-localization-typings-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Fheft-localization-typings-plugin) | [changelog](./heft-plugins/heft-localization-typings-plugin/CHANGELOG.md) | [@rushstack/heft-localization-typings-plugin](https://www.npmjs.com/package/@rushstack/heft-localization-typings-plugin) |
 | [/heft-plugins/heft-sass-load-themed-styles-plugin](./heft-plugins/heft-sass-load-themed-styles-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fheft-sass-load-themed-styles-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Fheft-sass-load-themed-styles-plugin) | [changelog](./heft-plugins/heft-sass-load-themed-styles-plugin/CHANGELOG.md) | [@rushstack/heft-sass-load-themed-styles-plugin](https://www.npmjs.com/package/@rushstack/heft-sass-load-themed-styles-plugin) |
@@ -175,6 +176,7 @@ These GitHub repositories provide supplementary resources for Rush Stack:
 | [/build-tests/heft-fastify-test](./build-tests/heft-fastify-test/) | This project tests Heft support for the Fastify framework for Node.js services |
 | [/build-tests/heft-jest-preset-test](./build-tests/heft-jest-preset-test/) | This project illustrates configuring a Jest preset in a minimal Heft project |
 | [/build-tests/heft-jest-reporters-test](./build-tests/heft-jest-reporters-test/) | This project illustrates configuring Jest reporters in a minimal Heft project |
+| [/build-tests/heft-json-schema-typings-plugin-test](./build-tests/heft-json-schema-typings-plugin-test/) | This project illustrates configuring Jest reporters in a minimal Heft project |
 | [/build-tests/heft-minimal-rig-test](./build-tests/heft-minimal-rig-test/) | This is a minimal rig package that is imported by the 'heft-minimal-rig-usage-test' project |
 | [/build-tests/heft-minimal-rig-usage-test](./build-tests/heft-minimal-rig-usage-test/) | A test project for Heft that resolves its compiler from the 'heft-minimal-rig-test' package |
 | [/build-tests/heft-node-everything-esm-module-test](./build-tests/heft-node-everything-esm-module-test/) | Building this project tests every task and config file for Heft when targeting the Node.js runtime when configured to use ESM module support |

build-tests/heft-json-schema-typings-plugin-test/config/heft.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/heft/v0/heft.schema.json",
+
+  "extends": "local-node-rig/profiles/default/config/heft.json",
+
+  "phasesByName": {
+    "build": {
+      "cleanFiles": [{ "includeGlobs": ["temp/schema-dts"] }],
+
+      "tasksByName": {
+        "json-schema-typings": {
+          "taskPlugin": {
+            "pluginPackage": "@rushstack/heft-json-schema-typings-plugin",
+            "pluginName": "json-schema-typings-plugin",
+            "options": {
+              "srcFolder": "node_modules/@rushstack/node-core-library/src/test/test-data/test-schemas",
+              "generatedTsFolders": ["temp/schema-dts"]
+            }
+          }
+        }
+      }
+    }
+  }
+}

build-tests/heft-json-schema-typings-plugin-test/config/jest.config.json

@@ -0,0 +1,3 @@
+{
+  "extends": "local-node-rig/profiles/default/config/jest.config.json"
+}

build-tests/heft-json-schema-typings-plugin-test/config/rig.json

@@ -0,0 +1,7 @@
+{
+  // The "rig.json" file directs tools to look for their config files in an external package.
+  // Documentation for this system: https://www.npmjs.com/package/@rushstack/rig-package
+  "$schema": "https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json",
+
+  "rigPackageName": "local-node-rig"
+}

build-tests/heft-json-schema-typings-plugin-test/eslint.config.js

@@ -0,0 +1,18 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+const nodeTrustedToolProfile = require('local-node-rig/profiles/default/includes/eslint/flat/profile/node-trusted-tool');
+const friendlyLocalsMixin = require('local-node-rig/profiles/default/includes/eslint/flat/mixins/friendly-locals');
+
+module.exports = [
+  ...nodeTrustedToolProfile,
+  ...friendlyLocalsMixin,
+  {
+    files: ['**/*.ts', '**/*.tsx'],
+    languageOptions: {
+      parserOptions: {
+        tsconfigRootDir: __dirname
+      }
+    }
+  }
+];

build-tests/heft-json-schema-typings-plugin-test/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "heft-json-schema-typings-plugin-test",
+  "description": "This project illustrates configuring Jest reporters in a minimal Heft project",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "build": "heft build --clean",
+    "start": "heft build-watch",
+    "_phase:build": "heft run --only build -- --clean",
+    "_phase:test": "heft run --only test -- --clean"
+  },
+  "devDependencies": {
+    "@rushstack/heft-json-schema-typings-plugin": "workspace:*",
+    "@rushstack/heft": "workspace:*",
+    "@rushstack/node-core-library": "workspace:*",
+    "eslint": "~9.25.1",
+    "local-node-rig": "workspace:*"
+  }
+}

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

@@ -0,0 +1,44 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import { FileSystem, type FolderItem, PackageJsonLookup } from '@rushstack/node-core-library';
+
+async function getFolderItemsAsync(
+  absolutePath: string,
+  relativePath: string
+): Promise<Record<string, string>> {
+  const folderQueue: [string, string][] = [[absolutePath, relativePath]];
+  const results: [string, string][] = [];
+  for (const [folderAbsolutePath, folderRelativePath] of folderQueue) {
+    const folderItems: FolderItem[] = await FileSystem.readFolderItemsAsync(folderAbsolutePath);
+    for (const item of folderItems) {
+      const itemName: string = item.name;
+      const itemAbsolutePath: string = `${folderAbsolutePath}/${itemName}`;
+      const itemRelativePath: string = `${folderRelativePath}/${itemName}`;
+      if (item.isDirectory()) {
+        folderQueue.push([itemAbsolutePath, itemRelativePath]);
+      } else {
+        const itemContents: string = await FileSystem.readFileAsync(itemAbsolutePath);
+        results.push([itemRelativePath, itemContents]);
+      }
+    }
+  }
+
+  results.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return Object.fromEntries(results);
+}
+
+describe('json-schema-typings-plugin', () => {
+  it('should generate typings for JSON Schemas', async () => {
+    const rootFolder: string | undefined = PackageJsonLookup.instance.tryGetPackageFolderFor(__dirname);
+    if (!rootFolder) {
+      throw new Error('Could not find root folder for the test');
+    }
+
+    const folderItems: Record<string, string> = await getFolderItemsAsync(
+      `${rootFolder}/temp/schema-dts`,
+      '.'
+    );
+    expect(folderItems).toMatchSnapshot();
+  });
+});

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

@@ -0,0 +1,185 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`json-schema-typings-plugin should generate typings for JSON Schemas 1`] = `
+Object {
+  "./test-invalid-additional.schema.json.d.ts": "// This file was generated by a tool. Modifying it will produce unexpected behavior
+
+export interface TestInvalidAdditional {
+  [k: string]: unknown;
+}
+",
+  "./test-invalid-format.schema.json.d.ts": "// This file was generated by a tool. Modifying it will produce unexpected behavior
+
+export interface TestInvalidFormat {
+  [k: string]: unknown;
+}
+",
+  "./test-schema-draft-04.schema.json.d.ts": "// This file was generated by a tool. Modifying it will produce unexpected behavior
+
+export interface TestSchemaFile {
+  exampleString: string;
+  exampleLink?: string;
+  exampleArray: string[];
+  /**
+   * Description for exampleOneOf - this is a very long description to show in an error message
+   */
+  exampleOneOf?: Type1 | Type2;
+  exampleUniqueObjectArray?: {
+    field2?: string;
+    field3?: string;
+  }[];
+}
+/**
+ * Description for type1
+ */
+export interface Type1 {
+  /**
+   * Description for field1
+   */
+  field1: string;
+}
+/**
+ * Description for type2
+ */
+export interface Type2 {
+  /**
+   * Description for field2
+   */
+  field2: string;
+  /**
+   * Description for field3
+   */
+  field3: string;
+}
+",
+  "./test-schema-draft-07.schema.json.d.ts": "// This file was generated by a tool. Modifying it will produce unexpected behavior
+
+export interface TestSchemaFile {
+  exampleString: string;
+  exampleLink?: string;
+  exampleArray: string[];
+  /**
+   * Description for exampleOneOf - this is a very long description to show in an error message
+   */
+  exampleOneOf?: Type1 | Type2;
+  exampleUniqueObjectArray?: {
+    field2?: string;
+    field3?: string;
+  }[];
+}
+/**
+ * Description for type1
+ */
+export interface Type1 {
+  /**
+   * Description for field1
+   */
+  field1: string;
+}
+/**
+ * Description for type2
+ */
+export interface Type2 {
+  /**
+   * Description for field2
+   */
+  field2: string;
+  /**
+   * Description for field3
+   */
+  field3: string;
+}
+",
+  "./test-schema-invalid.schema.json.d.ts": "// This file was generated by a tool. Modifying it will produce unexpected behavior
+
+export interface HttpExampleComSchemasTestSchemaNestedChildSchemaJson {
+  [k: string]: unknown;
+}
+",
+  "./test-schema-nested-child.schema.json.d.ts": "// This file was generated by a tool. Modifying it will produce unexpected behavior
+
+export interface HttpExampleComSchemasTestSchemaNestedChildSchemaJson {
+  [k: string]: unknown;
+}
+",
+  "./test-schema-nested.schema.json.d.ts": "// This file was generated by a tool. Modifying it will produce unexpected behavior
+
+export interface TestSchemaFile {
+  exampleString: string;
+  exampleLink?: string;
+  exampleArray: string[];
+  /**
+   * Description for exampleOneOf - this is a very long description to show in an error message
+   */
+  exampleOneOf?: Type1 | Type2;
+  exampleUniqueObjectArray?: Type2[];
+}
+/**
+ * Description for type1
+ */
+export interface Type1 {
+  /**
+   * Description for field1
+   */
+  field1: string;
+}
+/**
+ * Description for type2
+ */
+export interface Type2 {
+  /**
+   * Description for field2
+   */
+  field2: string;
+  /**
+   * Description for field3
+   */
+  field3: string;
+}
+",
+  "./test-schema.schema.json.d.ts": "// This file was generated by a tool. Modifying it will produce unexpected behavior
+
+export interface TestSchemaFile {
+  exampleString: string;
+  exampleLink?: string;
+  exampleArray: string[];
+  /**
+   * Description for exampleOneOf - this is a very long description to show in an error message
+   */
+  exampleOneOf?: Type1 | Type2;
+  exampleUniqueObjectArray?: {
+    field2?: string;
+    field3?: string;
+  }[];
+}
+/**
+ * Description for type1
+ */
+export interface Type1 {
+  /**
+   * Description for field1
+   */
+  field1: string;
+}
+/**
+ * Description for type2
+ */
+export interface Type2 {
+  /**
+   * Description for field2
+   */
+  field2: string;
+  /**
+   * Description for field3
+   */
+  field3: string;
+}
+",
+  "./test-valid.schema.json.d.ts": "// This file was generated by a tool. Modifying it will produce unexpected behavior
+
+export interface TestValid {
+  [k: string]: unknown;
+}
+",
+}
+`;

build-tests/heft-json-schema-typings-plugin-test/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "./node_modules/local-node-rig/profiles/default/tsconfig-base.json"
+}

common/changes/@rushstack/heft-json-schema-typings-plugin/user-ianc-json-schema-typings-plugin_2025-07-07-20-54.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/heft-json-schema-typings-plugin",
+      "comment": "Initial release.",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@rushstack/heft-json-schema-typings-plugin"
+}

common/changes/@rushstack/heft-web-rig/user-ianc-json-schema-typings-plugin_2025-07-07-22-05.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/heft-web-rig",
+      "comment": "Clean the temp/sass-ts folder.",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@rushstack/heft-web-rig"
+}

common/changes/@rushstack/node-core-library/user-ianc-json-schema-typings-plugin_2025-07-07-20-54.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/node-core-library",
+      "comment": "",
+      "type": "none"
+    }
+  ],
+  "packageName": "@rushstack/node-core-library"
+}

common/config/rush/browser-approved-packages.json

@@ -58,14 +58,6 @@
       "name": "dependency-path",
       "allowedCategories": [ "libraries" ]
     },
-    {
-      "name": "heft-example-lifecycle-plugin",
-      "allowedCategories": [ "tests" ]
-    },
-    {
-      "name": "local-web-rig",
-      "allowedCategories": [ "libraries", "vscode-extensions" ]
-    },
     {
       "name": "office-ui-fabric-core",
       "allowedCategories": [ "libraries" ]