docs(developer): create documentation for kmc convert 📚

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

@@ -8,18 +8,21 @@ import { CompilerCallbacks } from '@keymanapp/developer-utils';
 import { CompilerEvent } from '@keymanapp/developer-utils';
 import { CompilerOptions } from '@keymanapp/developer-utils';
 import { KeymanCompiler } from '@keymanapp/developer-utils';
+import { KeymanCompilerArtifactOptional } from '@keymanapp/developer-utils';
 import { KeymanCompilerArtifacts } from '@keymanapp/developer-utils';
 import { KeymanCompilerResult } from '@keymanapp/developer-utils';
 
 // @public
 export class Converter implements KeymanCompiler {
     init(callbacks: CompilerCallbacks, options: CompilerOptions): Promise<boolean>;
-    // Warning: (ae-forgotten-export) The symbol "ConverterResult" needs to be exported by the entry point main.d.ts
     run(inputFilename: string, outputFilename?: string): Promise<ConverterResult>;
-    // Warning: (ae-forgotten-export) The symbol "ConverterArtifacts" needs to be exported by the entry point main.d.ts
     write(artifacts: ConverterArtifacts): Promise<boolean>;
 }
 
+// @public (undocumented)
+export interface ConverterArtifacts extends KeymanCompilerArtifacts {
+}
+
 // Warning: (ae-internal-missing-underscore) The name "ConverterMessages" should be prefixed with an underscore because the declaration is marked as @internal
 //
 // @internal (undocumented)
@@ -96,6 +99,23 @@ export interface ConverterOptions extends CompilerOptions {
     failIfIncomplete?: boolean;
 }
 
+// @public (undocumented)
+export interface ConverterResult extends KeymanCompilerResult {
+    artifacts: ConverterArtifacts;
+}
+
+// @public
+export interface ConverterToKmnArtifacts extends ConverterArtifacts {
+    keymanTouchLayout?: KeymanCompilerArtifactOptional;
+    kmn?: KeymanCompilerArtifactOptional;
+    kvks?: KeymanCompilerArtifactOptional;
+}
+
+// @public (undocumented)
+export interface ConverterToKmnResult extends ConverterResult {
+    artifacts: ConverterToKmnArtifacts;
+}
+
 // (No @packageDocumentation comment for this package)
 
 ```

developer/docs/help/reference/api/index.md

@@ -9,6 +9,7 @@
 |  Package | Description |
 |  --- | --- |
 |  [@keymanapp/kmc-analyze](./kmc-analyze.md) | kmc-analyze - keyboard analysis classes, including tools for <code>&amp;displayMap</code>. |
+|  [@keymanapp/kmc-convert](./kmc-convert.md) | kmc-convert - conversion tool between keyboard layouts (e.g. .keylayout -> .kmn). |
 |  [@keymanapp/kmc-keyboard-info](./kmc-keyboard-info.md) |  |
 |  [@keymanapp/kmc-kmn](./kmc-kmn.md) | kmc-kmn - Keyman keyboard compiler |
 |  [@keymanapp/kmc-ldml](./kmc-ldml.md) |  |

developer/docs/help/reference/api/kmc-convert.md

@@ -0,0 +1,3 @@
+# kmc-convert
+
+no entry at present

developer/docs/help/reference/kmc/api/index.md

@@ -15,6 +15,7 @@ Module Name                                      | NPM Package
 -------------------------------------------------|-------------------------------------------------------|------------------------------------|---------------
 [kmc](../cli)                                    | [@keymanapp/kmc][kmc-npm]                             | [GitHub][kmc-github]               | The official command-line interface for all of the various compilers in Keyman Developer.
 [kmc-analyze](../../api/kmc-analyze)             | [@keymanapp/kmc-analyze][kmc-analyze-npm]             | [GitHub][kmc-analyze-github]       | Provides Keyman keyboard analysis tools.
+[kmc-convert](../../api/kmc-convert)             | [@keymanapp/kmc-convert][kmc-convert-npm]             | [GitHub][kmc-convert-github]       | Converts between keyboard layouts (e.g. .keylayout -> .kmn)
 [kmc-keyboard-info](../../api/kmc-keyboard-info) | [@keymanapp/kmc-keyboard-info][kmc-keyboard-info-npm] | [GitHub][kmc-keyboard-info-github] | Builds a .keyboard_info file from a Keyman keyboard project.
 [kmc-kmn](../../api/kmc-kmn)                     | [@keymanapp/kmc-kmn][kmc-kmn-npm]                     | [GitHub][kmc-kmn-github]           | Builds .kmn keyboards into .kmx binary keyboard files.
 [kmc-ldml](../../api/kmc-ldml)                   | [@keymanapp/kmc-ldml][kmc-ldml-npm]                   | [GitHub][kmc-ldml-github]          | Builds LDML .xml keyboards into Keyman .kmx binary keyboard files.
@@ -24,6 +25,7 @@ Module Name                                      | NPM Package
 
 [kmc-npm]: https://npmjs.com/package/@keymanapp/kmc
 [kmc-analyze-npm]: https://npmjs.com/package/@keymanapp/kmc-analyze
+[kmc-convert-npm]: https://npmjs.com/package/@keymanapp/kmc-convert
 [kmc-keyboard-info-npm]: https://npmjs.com/package/@keymanapp/kmc-keyboard-info
 [kmc-kmn-npm]: https://npmjs.com/package/@keymanapp/kmc-kmn
 [kmc-ldml-npm]: https://npmjs.com/package/@keymanapp/kmc-ldml
@@ -34,6 +36,7 @@ Module Name                                      | NPM Package
 
 [kmc-github]: https://github.com/keymanapp/keyman/tree/master/developer/src/kmc
 [kmc-analyze-github]: https://github.com/keymanapp/keyman/tree/master/developer/src/kmc-analyze
+[kmc-convert-github]: https://github.com/keymanapp/keyman/tree/master/developer/src/kmc-convert
 [kmc-keyboard-info-github]: https://github.com/keymanapp/keyman/tree/master/developer/src/kmc-keyboard-info
 [kmc-kmn-github]: https://github.com/keymanapp/keyman/tree/master/developer/src/kmc-kmn
 [kmc-ldml-github]: https://github.com/keymanapp/keyman/tree/master/developer/src/kmc-ldml

developer/docs/help/reference/kmc/cli/reference.md

@@ -505,6 +505,14 @@ folder, and the files in that folder will follow the
 
 : A short description of the project, in Markdown. (default: lexical model name)
 
+## `kmc convert` options
+
+Converts keyboard source files between formats e.g. .keylayout -> .kmn keeping the original name and saving the output with new extention 
+
+`-p, --out-path <filename>`
+
+: The target folder to write the copied project.
+
 ## `kmc copy` options
 
 Copies a keyboard or lexical model project, renaming files matching the original

developer/src/kmc-convert/src/keylayout-to-kmn/keylayout-file-reader.ts

@@ -24,7 +24,7 @@ export class KeylayoutFileReader {
    * @param  keyMapSelect the keyMapSelect element to find in keyMapSet
    * @return true if the keyMapSet element is found, false if not
    */
-  public findMapIndexinKeymap(jsonObj: Keylayout.KeylayoutXMLSourceFile, keyMapSelect: Keylayout.KL_KeyMapSelect): boolean {
+  private findMapIndexinKeymap(jsonObj: Keylayout.KeylayoutXMLSourceFile, keyMapSelect: Keylayout.KL_KeyMapSelect): boolean {
     for (const keyMapSet of jsonObj.keyboard.keyMapSet) {
       for (const keyMap of keyMapSet.keyMap) {
         if (keyMap['index'] === keyMapSelect.mapIndex) {
@@ -43,7 +43,7 @@ export class KeylayoutFileReader {
    * @param  keyMap the keyMap element to find in modifierMap
    * @return true if the keyMap element is found, false if not
    */
-  public findIndexinKeymapSelect(jsonObj: Keylayout.KeylayoutXMLSourceFile, keyMap: Keylayout.KL_KeyMap): boolean {
+  private findIndexinKeymapSelect(jsonObj: Keylayout.KeylayoutXMLSourceFile, keyMap: Keylayout.KL_KeyMap): boolean {
     for (const modifierMap of jsonObj.keyboard.modifierMap) {
       for (const keyMapSelect of modifierMap.keyMapSelect) {
         if (keyMapSelect['mapIndex'] === keyMap.index) {
@@ -61,7 +61,7 @@ export class KeylayoutFileReader {
    * @param  jsonObj the read keylayout data to be checked
    * @return true if all keyMapSelect elements have a corresponding keyMap element, false if not
    */
-  public checkForCorrespondingElements(jsonObj: Keylayout.KeylayoutXMLSourceFile): boolean {
+  private checkForCorrespondingElements(jsonObj: Keylayout.KeylayoutXMLSourceFile): boolean {
     let available = true;
 
     // check if all keyMapSelect elements have a corresponding keyMap element in the .keylayout file
@@ -83,7 +83,7 @@ export class KeylayoutFileReader {
   /**
    * @returns true if valid, false if invalid
    */
-  public validate(source: Keylayout.KeylayoutXMLSourceFile, inputFilename: string): boolean {
+  private validate(source: Keylayout.KeylayoutXMLSourceFile, inputFilename: string): boolean {
     if (!source) {
       this.callbacks.reportMessage(ConverterMessages.Error_UnableToReadFile({ inputFilename: inputFilename }));
       return false;
@@ -110,7 +110,7 @@ export class KeylayoutFileReader {
    * @param  source the object to be changed
    * @return object that contain only boxed arrays
    */
-  public boxArray(source: any) {
+  private boxArray(source: any) {
 
     boxXmlArray(source, 'modifierMap');
 
@@ -172,4 +172,13 @@ export class KeylayoutFileReader {
       return null;
     }
   }
+
+  /** @internal */
+  public unitTestEndpoints = {
+    findMapIndexinKeymap: this.findMapIndexinKeymap.bind(this),
+    findIndexinKeymapSelect: this.findIndexinKeymapSelect.bind(this),
+    checkForCorrespondingElements: this.checkForCorrespondingElements.bind(this),
+    validate: this.validate.bind(this),
+    boxArray: this.boxArray.bind(this),
+  };
 };