chore(developer): consolidate api-extractor usage in Developer

.gitignore

@@ -186,3 +186,7 @@ lcov.info
 
 # flag file for build script
 .configured
+
+# see common/tools/api-extractor/README.md
+tsdoc.json
+api-extractor.json

common/tools/api-extractor/README.md

@@ -0,0 +1,41 @@
+# Introduction
+
+These files are used by `typescript_run_api_extractor()` in typescript.inc.sh.
+
+This is setup only for Developer projects at this time as outputs go into
+developer/docs and developer/build; future generalization requires changing only
+`$report_temp` and `$report_folder` parameters in
+`typescript_run_api_extractor()`.
+
+## api-extractor.template.json
+
+* Reference: https://api-extractor.com
+
+api-extractor.template.json contains a template for api-extractor; these
+parameters cannot be passed in to the tool, so we modify this template as needed
+with the following parameters:
+
+* `$keyman_root`: the `$KEYMAN_ROOT` variable, with backslash \ translated to
+  forward slash /
+* `$index_d_ts`: the filename `index.d.ts` or the corresponding filename for the
+  entry point of the project
+* `$project_path`: the path for the module, relative to the base of the repo
+* `$report_temp`: a temporary path for output files for api-extractor
+* `$report_folder`: target folder for completed api-extractor API documentation
+
+## tsdoc.template.json
+
+* Reference: https://tsdoc.org/pages/packages/tsdoc-config/
+
+tsdoc.template.json is copied (unmodified) from this folder into tsdoc.json in
+project folders (alongside tsconfig.json) before running api-extractor and
+removed again afterwards; there is no way to specify an alternate location for
+the file.
+
+tsdoc.template.json includes a definition for "@since" which has been proposed
+in https://github.com/microsoft/tsdoc/issues/136.
+
+## Notes
+
+See also .github/workflows/api-verification.yml which does API validation of
+Core for desktop platforms.

developer/config/api-extractor.base.json → common/tools/api-extractor/api-extractor.base.json

@@ -161,7 +161,7 @@
      * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
      * DEFAULT VALUE: "<projectFolder>/etc/"
      */
-    "reportFolder": "../docs/api/etc/",
+    // "reportFolder": "../docs/api/etc/",
 
     /**
      * Specifies the folder where the temporary report file is written.  The file name portion is determined by
@@ -176,7 +176,7 @@
      * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
      * DEFAULT VALUE: "<projectFolder>/temp/"
      */
-    "reportTempFolder": "../build/api/",
+    // "reportTempFolder": "../build/api/",
 
     /**
      * Whether "forgotten exports" should be included in the API report file. Forgotten exports are declarations
@@ -206,7 +206,7 @@
      * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
      * DEFAULT VALUE: "<projectFolder>/build/temp/<unscopedPackageName>.api.json"
      */
-    "apiJsonFilePath": "../build/api/<unscopedPackageName>.api.json",
+    // "apiJsonFilePath": "../build/api/<unscopedPackageName>.api.json",
 
     /**
      * Whether "forgotten exports" should be included in the doc model file. Forgotten exports are declarations

common/tools/api-extractor/api-extractor.template.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+  "extends": "$keyman_root/common/tools/api-extractor/api-extractor.base.json",
+  "mainEntryPointFilePath": "<projectFolder>/build/src/$index_d_ts",
+  "docModel": {
+    "enabled": true,
+    "projectFolderUrl": "http://github.com/keymanapp/keyman/tree/master/$project_path",
+    "apiJsonFilePath": "$report_temp/<unscopedPackageName>.api.json"
+  },
+  "apiReport": {
+    "enabled": true,
+    "reportFolder": "$report_folder/",
+    "reportTempFolder": "$report_temp/"
+  }
+}

common/tools/api-extractor/tsdoc.template.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
+  "extends": ["@microsoft/api-extractor/extends/tsdoc-base.json"],
+  "tagDefinitions": [
+    {
+      "tagName": "@since",
+      "syntaxKind": "block",
+      "allowMultiple": false
+    }
+  ],
+
+  "supportForTags": {
+    "@since": true
+  }
+}

developer/docs/api/etc/kmc-copy.api.md

@@ -214,7 +214,7 @@ export interface CopierOptions extends CompilerBaseOptions {
     relocateExternalFiles?: boolean;
 }
 
-// @public (undocumented)
+// @public
 export class KeymanProjectCopier implements KeymanCompiler {
     // Warning: (ae-forgotten-export) The symbol "CopierAsyncCallbacks" needs to be exported by the entry point main.d.ts
     //

developer/docs/api/etc/kmc-kmn.api.md

@@ -933,29 +933,29 @@ declare namespace Osk {
 }
 export { Osk }
 
-// @public (undocumented)
+// @public
 function parseMapping(mapping: any): PuaMap;
 
-// @public (undocumented)
+// @public
 type PuaMap = {
     [index: string]: string;
 };
 
-// @public (undocumented)
+// @public
 function remapTouchLayout(source: TouchLayout.TouchLayoutFile, map: PuaMap): boolean;
 
-// @public (undocumented)
+// @public
 function remapVisualKeyboard(vk: VisualKeyboard.VisualKeyboard, map: PuaMap): boolean;
 
-// @public (undocumented)
+// @public
 interface StringRef {
     // (undocumented)
     str: string;
     // (undocumented)
     usages: StringRefUsage[];
 }
 
-// @public (undocumented)
+// @public
 interface StringRefUsage {
     // (undocumented)
     count: number;

developer/src/kmc-analyze/build.sh

@@ -27,5 +27,5 @@ builder_parse "$@"
 builder_run_action clean      rm -rf ./build/
 builder_run_action configure  node_select_version_and_npm_ci
 builder_run_action build      tsc --build
-builder_run_action api        api-extractor run --local --verbose
+builder_run_action api        typescript_run_api_extractor developer/src/kmc-analyze index.d.ts
 builder_run_action test       typescript_run_eslint_mocha_tests 75

developer/src/kmc-analyze/src/osk-character-use/index.ts

@@ -304,7 +304,7 @@ export class AnalyzeOskCharacterUse {
    *
    * - .json: returns the final aggregated data as an array of strings, which
    *   can be joined to form a JSON blob of an object with a single member,
-   *   `map`, which is an array of {@link Osk.StringResult} objects.
+   *   `map`, which is an array of {@link @keymanapp/kmc-kmn#Osk.StringResult} objects.
    *
    * @param    format - file format to return - can be '.txt', '.md', or '.json'
    * @returns  an array of strings, formatted according to the `format`
@@ -324,7 +324,7 @@ export class AnalyzeOskCharacterUse {
 
   /**
    * Load a JSON-format result file to merge from
-   * @param filename
+   * @param filename - the full path to the JSON result file to load
    * @returns
    */
   private loadPreviousMap(filename: string): Osk.StringResult[] {

developer/src/kmc-copy/build.sh

@@ -33,7 +33,7 @@ builder_parse "$@"
 builder_run_action clean      rm -rf ./build/
 builder_run_action configure  node_select_version_and_npm_ci
 builder_run_action build      tsc --build
-builder_run_action api        api-extractor run --local --verbose
+builder_run_action api        typescript_run_api_extractor developer/src/kmc-copy main.d.ts
 
 # note: `export TEST_SAVE_ARTIFACTS=1` to save a copy of artifacts to temp path
 # note: `export TEST_SAVE_FIXTURES=1` to get a copy of cloud-based fixtures saved to online/

developer/src/kmc-copy/src/KeymanProjectCopier.ts

@@ -81,6 +81,10 @@ export interface CopierResult extends KeymanCompilerResult {
   artifacts: CopierArtifacts;
 };
 
+/**
+ * @public
+ * Copy a project and rename internal references
+ */
 export class KeymanProjectCopier implements KeymanCompiler {
   options: CopierOptions;
   callbacks: CompilerCallbacks;
@@ -111,8 +115,8 @@ export class KeymanProjectCopier implements KeymanCompiler {
    * artifacts on success. The files are passed in by name, and the compiler
    * will use callbacks as passed to the {@link KeymanProjectCopier.init}
    * function to read any input files by disk.
-   * @param   source  Source file or folder to copy. Can be a local file or folder, https://github.com/.../repo[/path], or cloud:id
-   * @returns         Binary artifacts on success, null on failure.
+   * @param   source - Source file or folder to copy. Can be a local file or folder, https://github.com/.../repo[/path], or cloud:id
+   * @returns          Binary artifacts on success, null on failure.
    */
   public async run(source: string): Promise<CopierResult> {
 
@@ -174,7 +178,7 @@ export class KeymanProjectCopier implements KeymanCompiler {
   /**
    * Resolve the source project file to either a local filesystem file,
    * or a reference on GitHub
-   * @param source
+   * @param source - URI to a project file
    * @returns  path to .kpj (either local or remote)
    */
   private async getSourceProject(source: string): Promise<string | GitHubRef> {
@@ -196,7 +200,7 @@ export class KeymanProjectCopier implements KeymanCompiler {
   /**
    * Resolve source path to the contained project file; the project
    * file must have the same basename as the folder in this case
-   * @param source
+   * @param source - local file path to a .kpj project file
    * @returns
    */
   private getLocalFolderProject(source: string): string {
@@ -212,7 +216,7 @@ export class KeymanProjectCopier implements KeymanCompiler {
   /**
    * Resolve source path to the input .kpj filename, folder name
    * is not relevant when .kpj filename is passed in
-   * @param source
+   * @param source - local file path to a .kpj project file
    * @returns
    */
   private getLocalFileProject(source: string): string {
@@ -224,7 +228,7 @@ export class KeymanProjectCopier implements KeymanCompiler {
    *   `[https://]github.com/owner/repo/branch/path/to/kpj`
    * The path must be fully qualified, referencing the .kpj file; it
    * cannot just be the folder where the .kpj is found
-   * @param source
+   * @param source - URL to a .kpj project file on GitHub
    * @returns a promise: GitHub reference to the source for the keyboard, or null on failure
    */
   private async getGitHubSourceProject(source: string): Promise<GitHubRef> {
@@ -273,7 +277,7 @@ export class KeymanProjectCopier implements KeymanCompiler {
    * The `keyboard_id` parameter should be a valid id (a-z0-9_), as found at
    * https://keyman.com/keyboards; alternatively if it is a model_id, it should
    * have the format author.bcp47.uniq
-   * @param source
+   * @param source - a reference to a keyboard or model project on Keyman Cloud
    * @returns a promise: GitHub reference to the source for the keyboard, or null on failure
    */
   private async getCloudSourceProject(source: string): Promise<GitHubRef> {
@@ -613,8 +617,8 @@ export class KeymanProjectCopier implements KeymanCompiler {
   /**
    * renames matching filename to the output filename pattern, and prepends the
    * outputPath
-   * @param filename
-   * @param outputPath
+   * @param filename - input filename to rename
+   * @param outputPath - target filename path
    * @returns
    */
   private generateNewFilename(filename: string, outputPath: string): string {

developer/src/kmc-generate/build.sh

@@ -39,5 +39,5 @@ do_build() {
 builder_run_action clean      rm -rf ./build/ ./tsconfig.tsbuildinfo
 builder_run_action configure  node_select_version_and_npm_ci
 builder_run_action build      do_build
-builder_run_action api        api-extractor run --local --verbose
+builder_run_action api        typescript_run_api_extractor developer/src/kmc-generate main.d.ts
 builder_run_action test       typescript_run_eslint_mocha_tests

developer/src/kmc-keyboard-info/build.sh

@@ -32,7 +32,7 @@ builder_parse "$@"
 builder_run_action clean       rm -rf ./build/ ./tsconfig.tsbuildinfo
 builder_run_action configure   node_select_version_and_npm_ci
 builder_run_action build       tsc --build
-builder_run_action api         api-extractor run --local --verbose
+builder_run_action api         typescript_run_api_extractor developer/src/kmc-keyboard-info index.d.ts
 builder_run_action test        typescript_run_eslint_mocha_tests
 
 #-------------------------------------------------------------------------------------------------------------------

developer/src/kmc-kmn/build.sh

@@ -65,5 +65,5 @@ function do_test() {
 }
 
 builder_run_action build      do_build
-builder_run_action api        api-extractor run --local --verbose
+builder_run_action api        typescript_run_api_extractor developer/src/kmc-kmn main.d.ts
 builder_run_action test       do_test