[typings-generator] Add some options to typings generation and introd…

…uce a Heft plugin for generating loc file typings. (#4894) * Include an option for a documentation comment for typings default exports. * Add options to parseAndGenerateTypings return. * Include a inferDefaultExportInterfaceNameFromFilename option for TypingsGenerator. * Add a heft plugin for generating localization file tyings. * Clean up inferred exports names. * Fix an issue and leave a note. * Update Readme. * Rename getVerbose to getVerboseOutput. * General updates and cleanup to make the change not breaking. * Introduce a test for StringValuesTypingsGenerator. * Rush change. * Code cleanup. * Random code cleanup in API Extractor. * Add a Text.splitByNewLines function to NCL. * Code cleanup. * Add slashNormalizedBuildFolderPath property to HeftConfiguration. * Tweak schema. * Add a test case for the loc typings generator plugin. * Work around an API Extractor issue.
microsoft · Aug 21, 2024 · 506e6a5 · 506e6a5
1 parent 2f08f7b
commit 506e6a5
Show file tree

Hide file tree

Showing 67 changed files with 1,438 additions and 203 deletions.
diff --git a/README.md b/README.md
@@ -65,6 +65,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-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-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-plugin](./heft-plugins/heft-sass-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fheft-sass-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Fheft-sass-plugin) | [changelog](./heft-plugins/heft-sass-plugin/CHANGELOG.md) | [@rushstack/heft-sass-plugin](https://www.npmjs.com/package/@rushstack/heft-sass-plugin) |
 | [/heft-plugins/heft-serverless-stack-plugin](./heft-plugins/heft-serverless-stack-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fheft-serverless-stack-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Fheft-serverless-stack-plugin) | [changelog](./heft-plugins/heft-serverless-stack-plugin/CHANGELOG.md) | [@rushstack/heft-serverless-stack-plugin](https://www.npmjs.com/package/@rushstack/heft-serverless-stack-plugin) |
 | [/heft-plugins/heft-storybook-plugin](./heft-plugins/heft-storybook-plugin/) | [![npm version](https://badge.fury.io/js/%40rushstack%2Fheft-storybook-plugin.svg)](https://badge.fury.io/js/%40rushstack%2Fheft-storybook-plugin) | [changelog](./heft-plugins/heft-storybook-plugin/CHANGELOG.md) | [@rushstack/heft-storybook-plugin](https://www.npmjs.com/package/@rushstack/heft-storybook-plugin) |

diff --git a/apps/api-extractor/src/analyzer/Span.ts b/apps/api-extractor/src/analyzer/Span.ts
@@ -2,7 +2,7 @@
 // See LICENSE in the project root for license information.
 
 import * as ts from 'typescript';
-import { InternalError, Sort } from '@rushstack/node-core-library';
+import { InternalError, Sort, Text } from '@rushstack/node-core-library';
 
 import { IndentedWriter } from '../generators/IndentedWriter';
 
@@ -637,12 +637,7 @@ export class Span {
   }
 
   private _getTrimmed(text: string): string {
-    const trimmed: string = text.replace(/\r?\n/g, '\\n');
-
-    if (trimmed.length > 100) {
-      return trimmed.substr(0, 97) + '...';
-    }
-    return trimmed;
+    return Text.truncateWithEllipsis(Text.convertToLf(text), 100);
   }
 
   private _getSubstring(startIndex: number, endIndex: number): string {

diff --git a/apps/heft/src/configuration/HeftConfiguration.ts b/apps/heft/src/configuration/HeftConfiguration.ts
@@ -2,7 +2,7 @@
 // See LICENSE in the project root for license information.
 
 import * as path from 'path';
-import { type IPackageJson, PackageJsonLookup, InternalError } from '@rushstack/node-core-library';
+import { type IPackageJson, PackageJsonLookup, InternalError, Path } from '@rushstack/node-core-library';
 import { Terminal, type ITerminalProvider, type ITerminal } from '@rushstack/terminal';
 import { trueCasePathSync } from 'true-case-path';
 import { type IRigConfig, RigConfig } from '@rushstack/rig-package';
@@ -30,8 +30,8 @@ export interface IHeftConfigurationInitializationOptions {
  */
 export class HeftConfiguration {
   private _buildFolderPath!: string;
+  private _slashNormalizedBuildFolderPath: string | undefined;
   private _projectConfigFolderPath: string | undefined;
-  private _cacheFolderPath: string | undefined;
   private _tempFolderPath: string | undefined;
   private _rigConfig: IRigConfig | undefined;
   private _globalTerminal!: Terminal;
@@ -45,6 +45,17 @@ export class HeftConfiguration {
     return this._buildFolderPath;
   }
 
+  /**
+   * {@link HeftConfiguration.buildFolderPath} with all path separators converted to forward slashes.
+   */
+  public get slashNormalizedBuildFolderPath(): string {
+    if (!this._slashNormalizedBuildFolderPath) {
+      this._slashNormalizedBuildFolderPath = Path.convertToSlashes(this.buildFolderPath);
+    }
+
+    return this._slashNormalizedBuildFolderPath;
+  }
+
   /**
    * The path to the project's "config" folder.
    */

diff --git a/apps/heft/src/utilities/GitUtilities.ts b/apps/heft/src/utilities/GitUtilities.ts
@@ -4,7 +4,7 @@
 import * as path from 'path';
 import type { ChildProcess, SpawnSyncReturns } from 'child_process';
 import { default as getGitRepoInfo, type GitRepoInfo as IGitRepoInfo } from 'git-repo-info';
-import { Executable, FileSystem, InternalError, Path } from '@rushstack/node-core-library';
+import { Executable, FileSystem, InternalError, Path, Text } from '@rushstack/node-core-library';
 import { default as ignore, type Ignore as IIgnoreMatcher } from 'ignore';
 
 // Matches lines starting with "#" and whitepace lines
@@ -282,7 +282,7 @@ export class GitUtilities {
 
     const foundIgnorePatterns: string[] = [];
     if (gitIgnoreContent) {
-      const gitIgnorePatterns: string[] = gitIgnoreContent.split(/\r?\n/g);
+      const gitIgnorePatterns: string[] = Text.splitByNewLines(gitIgnoreContent);
       for (const gitIgnorePattern of gitIgnorePatterns) {
         // Ignore whitespace-only lines and comments
         if (gitIgnorePattern.length === 0 || GITIGNORE_IGNORABLE_LINE_REGEX.test(gitIgnorePattern)) {

diff --git a/build-tests/localization-plugin-test-02/build.js b/build-tests/localization-plugin-test-02/build.js
diff --git a/build-tests/localization-plugin-test-02/config/heft.json b/build-tests/localization-plugin-test-02/config/heft.json
@@ -0,0 +1,42 @@
+/**
+ * Defines configuration used by core Heft.
+ */
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/heft/v0/heft.schema.json",
+
+  // TODO: Add comments
+  "phasesByName": {
+    "build": {
+      "cleanFiles": [{ "includeGlobs": ["dist", "lib", "lib-commonjs"] }],
+
+      "tasksByName": {
+        "loc-typings": {
+          "taskPlugin": {
+            "pluginPackage": "@rushstack/heft-localization-typings-plugin",
+            "options": {
+              "generatedTsFolder": "temp/loc-json-ts"
+            }
+          }
+        },
+        "typescript": {
+          "taskDependencies": ["loc-typings"],
+          "taskPlugin": {
+            "pluginPackage": "@rushstack/heft-typescript-plugin"
+          }
+        },
+        "lint": {
+          "taskDependencies": ["typescript"],
+          "taskPlugin": {
+            "pluginPackage": "@rushstack/heft-lint-plugin"
+          }
+        },
+        "webpack": {
+          "taskDependencies": ["typescript"],
+          "taskPlugin": {
+            "pluginPackage": "@rushstack/heft-webpack4-plugin"
+          }
+        }
+      }
+    }
+  }
+}
diff --git a/build-tests/localization-plugin-test-02/config/rush-project.json b/build-tests/localization-plugin-test-02/config/rush-project.json
@@ -4,7 +4,7 @@
   "operationSettings": [
     {
       "operationName": "_phase:build",
-      "outputFolderNames": ["lib", "dist"]
+      "outputFolderNames": ["lib", "dist-dev", "dist-prod"]
     }
   ]
 }
diff --git a/build-tests/localization-plugin-test-02/config/typescript.json b/build-tests/localization-plugin-test-02/config/typescript.json
@@ -0,0 +1,10 @@
+/**
+ * Configures the TypeScript plugin for Heft.  This plugin also manages linting.
+ */
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/heft/v0/typescript.schema.json",
+
+  "staticAssetsToCopy": {
+    "fileExtensions": [".resx", ".json", ".resjson"]
+  }
+}
diff --git a/build-tests/localization-plugin-test-02/package.json b/build-tests/localization-plugin-test-02/package.json
@@ -4,20 +4,24 @@
   "version": "0.1.0",
   "private": true,
   "scripts": {
-    "build": "node build.js",
-    "serve": "node serve.js",
-    "_phase:build": "node build.js"
+    "build": "heft build --clean",
+    "start": "heft start",
+    "_phase:build": "heft run --only build -- --clean"
   },
   "dependencies": {
-    "@rushstack/webpack4-localization-plugin": "workspace:*",
-    "@rushstack/webpack4-module-minifier-plugin": "workspace:*",
+    "@rushstack/heft-lint-plugin": "workspace:*",
+    "@rushstack/heft-localization-typings-plugin": "workspace:*",
+    "@rushstack/heft-typescript-plugin": "workspace:*",
+    "@rushstack/heft-webpack4-plugin": "workspace:*",
+    "@rushstack/heft": "workspace:*",
     "@rushstack/node-core-library": "workspace:*",
     "@rushstack/set-webpack-public-path-plugin": "^4.1.16",
+    "@rushstack/webpack4-localization-plugin": "workspace:*",
+    "@rushstack/webpack4-module-minifier-plugin": "workspace:*",
     "@types/lodash": "4.14.116",
     "@types/webpack-env": "1.18.0",
     "html-webpack-plugin": "~4.5.2",
     "lodash": "~4.17.15",
-    "ts-loader": "6.0.0",
     "typescript": "~5.4.2",
     "webpack-bundle-analyzer": "~4.5.0",
     "webpack-cli": "~3.3.2",

diff --git a/build-tests/localization-plugin-test-02/serve.js b/build-tests/localization-plugin-test-02/serve.js
diff --git a/build-tests/localization-plugin-test-02/src/indexA.ts b/build-tests/localization-plugin-test-02/src/indexA.ts
@@ -1,5 +1,5 @@
 import { string1 } from './strings1.loc.json';
-import * as strings3 from './strings3.loc.json';
+import * as strings3 from './strings3.resjson';
 import * as strings5 from './strings5.resx';
 
 console.log(string1);

diff --git a/build-tests/localization-plugin-test-02/src/indexB.ts b/build-tests/localization-plugin-test-02/src/indexB.ts
@@ -1,4 +1,4 @@
-import { string1, string2 } from './strings3.loc.json';
+import { string1, string2 } from './strings3.resjson';
 const strings4: string = require('./strings4.loc.json');
 
 console.log(string1);

diff --git a/build-tests/localization-plugin-test-02/src/strings3.loc.json b/build-tests/localization-plugin-test-02/src/strings3.loc.json
diff --git a/build-tests/localization-plugin-test-02/src/strings3.resjson b/build-tests/localization-plugin-test-02/src/strings3.resjson
@@ -0,0 +1,10 @@
+{
+  "string1": "string three with a \\ backslash",
+  "_string1.comment": "the third string",
+
+  "string2": "string four with an ' apostrophe",
+  "_string2.comment": "the fourth string",
+
+  "string3": "UNUSED STRING",
+  "_string3.comment":  "UNUSED STRING"
+}
diff --git a/build-tests/localization-plugin-test-02/webpack.config.js b/build-tests/localization-plugin-test-02/webpack.config.js
@@ -12,30 +12,13 @@ const HtmlWebpackPlugin = require('html-webpack-plugin');
 function generateConfiguration(mode, outputFolderName) {
   return {
     mode: mode,
-    module: {
-      rules: [
-        {
-          test: /\.tsx?$/,
-          loader: require.resolve('ts-loader'),
-          exclude: /(node_modules)/,
-          options: {
-            compiler: require.resolve('typescript'),
-            logLevel: 'ERROR',
-            configFile: path.resolve(__dirname, 'tsconfig.json')
-          }
-        }
-      ]
-    },
-    resolve: {
-      extensions: ['.js', '.jsx', '.json', '.ts', '.tsx']
-    },
     entry: {
-      'localization-test-A': path.join(__dirname, 'src', 'indexA.ts'),
-      'localization-test-B': path.join(__dirname, 'src', 'indexB.ts'),
-      'localization-test-C': path.join(__dirname, 'src', 'indexC.ts')
+      'localization-test-A': `${__dirname}/lib/indexA.js`,
+      'localization-test-B': `${__dirname}/lib/indexB.js`,
+      'localization-test-C': `${__dirname}/lib/indexC.js`
     },
     output: {
-      path: path.join(__dirname, outputFolderName),
+      path: `${__dirname}/${outputFolderName}`,
       filename: '[name]_[locale]_[contenthash].js',
       chunkFilename: '[id].[name]_[locale]_[contenthash].js'
     },
@@ -84,22 +67,17 @@ function generateConfiguration(mode, outputFolderName) {
           normalizeResxNewlines: 'crlf',
           ignoreMissingResxComments: true
         },
-        typingsOptions: {
-          generatedTsFolder: path.resolve(__dirname, 'temp', 'loc-json-ts'),
-          sourceRoot: path.resolve(__dirname, 'src'),
-          processComment: (comment) => (comment ? `${comment} (processed)` : comment)
-        },
         localizationStats: {
-          dropPath: path.resolve(__dirname, 'temp', 'localization-stats.json')
+          dropPath: `${__dirname}/temp/localization-stats.json`
         },
         ignoreString: (filePath, stringName) => stringName === '__IGNORED_STRING__'
       }),
       new BundleAnalyzerPlugin({
         openAnalyzer: false,
         analyzerMode: 'static',
-        reportFilename: path.resolve(__dirname, 'temp', 'stats.html'),
+        reportFilename: `${__dirname}/temp/stats.html`,
         generateStatsFile: true,
-        statsFilename: path.resolve(__dirname, 'temp', 'stats.json'),
+        statsFilename: `${__dirname}/temp/stats.json`,
         logLevel: 'error'
       }),
       new SetPublicPathPlugin({

diff --git a/common/changes/@microsoft/api-extractor/loc-typings-heft-plugin_2024-08-21-00-29.json b/common/changes/@microsoft/api-extractor/loc-typings-heft-plugin_2024-08-21-00-29.json
@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "comment": "",
+      "type": "none"
+    }
+  ],
+  "packageName": "@microsoft/api-extractor"
+}
diff --git a/common/changes/@microsoft/rush/loc-typings-heft-plugin_2024-08-20-22-59.json b/common/changes/@microsoft/rush/loc-typings-heft-plugin_2024-08-20-22-59.json
@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/rush",
+      "comment": "",
+      "type": "none"
+    }
+  ],
+  "packageName": "@microsoft/rush"
+}
diff --git a/common/changes/@rushstack/heft-config-file/loc-typings-heft-plugin_2024-08-20-22-59.json b/common/changes/@rushstack/heft-config-file/loc-typings-heft-plugin_2024-08-20-22-59.json
@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/heft-config-file",
+      "comment": "",
+      "type": "none"
+    }
+  ],
+  "packageName": "@rushstack/heft-config-file"
+}
diff --git a/...stack/heft-localization-typings-plugin/loc-typings-heft-plugin-impl_2024-08-17-00-18.json b/...stack/heft-localization-typings-plugin/loc-typings-heft-plugin-impl_2024-08-17-00-18.json
@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/heft-localization-typings-plugin",
+      "comment": "Initial release.",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@rushstack/heft-localization-typings-plugin"
+}
diff --git a/common/changes/@rushstack/heft-sass-plugin/loc-typings-heft-plugin_2024-08-21-00-55.json b/common/changes/@rushstack/heft-sass-plugin/loc-typings-heft-plugin_2024-08-21-00-55.json
@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/heft-sass-plugin",
+      "comment": "",
+      "type": "none"
+    }
+  ],
+  "packageName": "@rushstack/heft-sass-plugin"
+}
diff --git a/common/changes/@rushstack/heft/loc-typings-heft-plugin_2024-08-21-00-55.json b/common/changes/@rushstack/heft/loc-typings-heft-plugin_2024-08-21-00-55.json
@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/heft",
+      "comment": "Add a `slashNormalizedBuildFolderPath` property to `HeftConfiguration`.",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@rushstack/heft"
+}