Merge pull request #9621 from keymanapp/chore/developer/9620-validate-keyboard_info-and-fix-keys

chore(developer): validate emitted .keyboard_info and fix keys 🎺

Author: mcdurdin

common/schemas/keyboard_info/keyboard_info.schema.json

@@ -22,8 +22,8 @@
         "jsFilename": { "type": "string", "pattern": "\\.js$" },
         "jsFileSize": { "type": "number" },
         "isRTL": { "type": "boolean" },
-        "encodings": { "type": "array", "items": { "type": "string", "enum": ["ansi", "unicode"] }, "additionalItems": false },
-        "packageIncludes": { "type": "array", "items": { "type": "string", "enum": ["welcome", "documentation", "fonts", "visualKeyboard"] }, "additionalItems": false },
+        "encodings": { "type": "array", "items": { "type": "string", "enum": ["ansi", "unicode"] } },
+        "packageIncludes": { "type": "array", "items": { "type": "string", "enum": ["welcome", "documentation", "fonts", "visualKeyboard"] } },
         "version": { "type": "string" },
         "minKeymanVersion": { "type": "string", "pattern": "^\\d+\\.\\d$" },
         "helpLink": { "type": "string", "pattern": "^https://help\\.keyman\\.com/keyboard/" },

common/web/types/src/package/kmp-json-file.ts

@@ -97,7 +97,17 @@ export interface KmpJsonFileExample {
    */
   id: string;
   /**
-   * A space-separated list of keys, modifiers indicated with "+", spacebar is "space", plus key is "shift+=" or "plus"
+   * A space-separated list of keys.
+   * - modifiers indicated with "+"
+   * - spacebar is "space"
+   * - plus key is "shift+=" or "plus" on US English (all other punctuation as per key cap).
+   * - Hardware modifiers are: "shift", "ctrl", "alt", "left-ctrl",
+   *   "right-ctrl", "left-alt", "right-alt"
+   * - Key caps should generally be their character for desktop (Latin script
+   *   case insensitive), or the actual key cap for touch
+   * - Caps Lock should be indicated with "caps-on", "caps-off"
+   *
+   * e.g. "shift+a b right-alt+c space plus z z z" represents something like: "Ab{AltGr+C} +zzz"
    */
   keys: string;
   /**

common/web/types/src/package/kps-file.ts

@@ -184,7 +184,17 @@ export interface KpsFileLanguageExample {
      */
     ID: string;
     /**
-     * A space-separated list of keys, modifiers indicated with "+", spacebar is "space", plus key is "shift+=" or "plus"
+     * A space-separated list of keys.
+     * - modifiers indicated with "+"
+     * - spacebar is "space"
+     * - plus key is "shift+=" or "plus" on US English (all other punctuation as per key cap).
+     * - Hardware modifiers are: "shift", "ctrl", "alt", "left-ctrl",
+     *   "right-ctrl", "left-alt", "right-alt"
+     * - Key caps should generally be their character for desktop (Latin script
+     *   case insensitive), or the actual key cap for touch
+     * - Caps Lock should be indicated with "caps-on", "caps-off"
+     *
+     * e.g. "shift+a b right-alt+c space plus z z z" represents something like: "Ab{AltGr+C} +zzz"
      */
     Keys: string;
     /**

developer/src/common/delphi/compiler/Keyman.Developer.System.ValidateKpsFile.pas

@@ -26,7 +26,9 @@
   "dependencies": {
     "@keymanapp/common-types": "*",
     "@keymanapp/kmc-package": "*",
-    "@keymanapp/developer-utils": "*"
+    "@keymanapp/developer-utils": "*",
+    "ajv": "^8.11.0",
+    "ajv-formats": "^2.1.1"
   },
   "bundleDependencies": [
     "@keymanapp/developer-utils"

developer/src/kmc-keyboard-info/package.json

@@ -0,0 +1,23 @@
+import { KeyboardInfoFileExampleKey } from "./keyboard-info-file.js";
+
+/**
+ * Converts a .kps or .kmp example keys string into an array of key objects
+ * matching the .keyboard_info example file format
+ * @param keysString
+ * @returns
+ */
+export function packageKeysExamplesToKeyboardInfo(keysString: string): KeyboardInfoFileExampleKey[] {
+  const items = keysString.trim().split(/ +/);
+  const result: KeyboardInfoFileExampleKey[] = [];
+  for(const item of items) {
+    const keyAndModifiers = item.split('+');
+    if(keyAndModifiers.length > 0) {
+      const key: KeyboardInfoFileExampleKey = {key: keyAndModifiers.pop()}
+      if(keyAndModifiers.length) {
+        key.modifiers = [...keyAndModifiers];
+      };
+      result.push(key);
+    }
+  }
+  return result;
+}

developer/src/kmc-keyboard-info/src/example-keys.ts

@@ -11,6 +11,14 @@ import langtags from "./imports/langtags.js";
 import { validateMITLicense } from "@keymanapp/developer-utils";
 import { KmpCompiler } from "@keymanapp/kmc-package";
 
+import AjvModule from 'ajv';
+import AjvFormatsModule from 'ajv-formats';
+const Ajv = AjvModule.default; // The actual expected Ajv type.
+const ajvFormats = AjvFormatsModule.default;
+
+import { Schemas } from "@keymanapp/common-types";
+import { packageKeysExamplesToKeyboardInfo } from "./example-keys.js";
+
 const regionNames = new Intl.DisplayNames(['en'], { type: "region" });
 const scriptNames = new Intl.DisplayNames(['en'], { type: "script" });
 const langtagsByTag = {};
@@ -281,6 +289,20 @@ export class KeyboardInfoCompiler {
     }
 
     const jsonOutput = JSON.stringify(keyboard_info, null, 2);
+
+    // TODO: look at performance improvements by precompiling Ajv schemas on first use
+    const ajv = new Ajv({ logger: {
+      log: (message) => this.callbacks.reportMessage(KeyboardInfoCompilerMessages.Hint_OutputValidation({message})),
+      warn: (message) => this.callbacks.reportMessage(KeyboardInfoCompilerMessages.Warn_OutputValidation({message})),
+      error: (message) => this.callbacks.reportMessage(KeyboardInfoCompilerMessages.Error_OutputValidation({message})),
+    }});
+    ajvFormats.default(ajv);
+    if(!ajv.validate(Schemas.default.keyboard_info, keyboard_info)) {
+      // This is an internal fatal error; we should not be capable of producing
+      // invalid output, so it is best to throw and die
+      throw new Error(ajv.errorsText());
+    }
+
     return new TextEncoder().encode(jsonOutput);
   }
 
@@ -380,9 +402,9 @@ export class KeyboardInfoCompiler {
         if(example.id == bcp47) {
           language.examples.push({
             // we don't copy over example.id
-            keys:example.keys,
-            note:example.note,
-            text:example.text
+            keys: packageKeysExamplesToKeyboardInfo(example.keys),
+            note: example.note,
+            text: example.text
           });
         }
       }

developer/src/kmc-keyboard-info/src/index.ts

@@ -49,7 +49,12 @@ export interface KeyboardInfoFileLanguageFont {
 }
 
 export interface KeyboardInfoFileExample {
-  keys?: string;
+  keys?: KeyboardInfoFileExampleKey[];
   text?: string;
   note?: string;
 }
+
+export interface KeyboardInfoFileExampleKey {
+  key: string;
+  modifiers?: string[];
+}

developer/src/kmc-keyboard-info/src/keyboard-info-file.ts

@@ -2,7 +2,7 @@ import { CompilerErrorNamespace, CompilerErrorSeverity, CompilerMessageSpec as m
 
 const Namespace = CompilerErrorNamespace.KeyboardInfoCompiler;
 // const SevInfo = CompilerErrorSeverity.Info | Namespace;
-// const SevHint = CompilerErrorSeverity.Hint | Namespace;
+const SevHint = CompilerErrorSeverity.Hint | Namespace;
 const SevWarn = CompilerErrorSeverity.Warn | Namespace;
 const SevError = CompilerErrorSeverity.Error | Namespace;
 const SevFatal = CompilerErrorSeverity.Fatal | Namespace;
@@ -45,5 +45,17 @@ export class KeyboardInfoCompilerMessages {
   static Error_NoLicenseFound = () => m(this.ERROR_NoLicenseFound,
     `No license for the keyboard was found. MIT license is required for publication to Keyman keyboards repository.`);
   static ERROR_NoLicenseFound = SevError | 0x000A;
+
+  static Hint_OutputValidation = (o:{message: any}) => m(this.HINT_OutputValidation,
+    `Validating output: ${o.message}.`);
+  static HINT_OutputValidation = SevHint | 0x000B;
+
+  static Warn_OutputValidation = (o:{message: any}) => m(this.WARN_OutputValidation,
+    `Validating output: ${o.message}.`);
+  static WARN_OutputValidation = SevWarn | 0x000C;
+
+  static Error_OutputValidation = (o:{message: any}) => m(this.ERROR_OutputValidation,
+    `Validating output: ${o.message}.`);
+  static ERROR_OutputValidation = SevError | 0x000D;
 }
 

developer/src/kmc-keyboard-info/src/messages.ts

@@ -15,7 +15,13 @@
         ]
       },
       "examples": [{
-        "keys": "x j m E r",
+        "keys": [
+          { "key": "x" },
+          { "key": "j" },
+          { "key": "m" },
+          { "key": "E" },
+          { "key": "r" }
+        ],
         "text": "\u1781\u17D2\u1798\u17C2\u179A",
         "note": "Name of language"
       }],