[typings-generator] Add some options to typings generation and introduce a Heft plugin for generating loc file typings. (microsoft#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.

Author: iclanton

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

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 {

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

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)) {

build-tests/localization-plugin-test-02/build.js

@@ -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"
+          }
+        }
+      }
+    }
+  }
+}

build-tests/localization-plugin-test-02/config/heft.json

@@ -4,7 +4,7 @@
   "operationSettings": [
     {
       "operationName": "_phase:build",
-      "outputFolderNames": ["lib", "dist"]
+      "outputFolderNames": ["lib", "dist-dev", "dist-prod"]
     }
   ]
 }

build-tests/localization-plugin-test-02/config/rush-project.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"]
+  }
+}

build-tests/localization-plugin-test-02/config/typescript.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",

build-tests/localization-plugin-test-02/package.json

@@ -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);

build-tests/localization-plugin-test-02/serve.js

@@ -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);

build-tests/localization-plugin-test-02/src/indexA.ts

@@ -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"
+}

build-tests/localization-plugin-test-02/src/indexB.ts

@@ -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({

build-tests/localization-plugin-test-02/src/strings3.loc.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "comment": "",
+      "type": "none"
+    }
+  ],
+  "packageName": "@microsoft/api-extractor"
+}

build-tests/localization-plugin-test-02/src/strings3.resjson

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/rush",
+      "comment": "",
+      "type": "none"
+    }
+  ],
+  "packageName": "@microsoft/rush"
+}

build-tests/localization-plugin-test-02/webpack.config.js

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/heft-config-file",
+      "comment": "",
+      "type": "none"
+    }
+  ],
+  "packageName": "@rushstack/heft-config-file"
+}

common/changes/@microsoft/api-extractor/loc-typings-heft-plugin_2024-08-21-00-29.json

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

common/changes/@microsoft/rush/loc-typings-heft-plugin_2024-08-20-22-59.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/heft-sass-plugin",
+      "comment": "",
+      "type": "none"
+    }
+  ],
+  "packageName": "@rushstack/heft-sass-plugin"
+}

common/changes/@rushstack/heft-config-file/loc-typings-heft-plugin_2024-08-20-22-59.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/heft",
+      "comment": "Add a `slashNormalizedBuildFolderPath` property to `HeftConfiguration`.",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@rushstack/heft"
+}