refactor(developer): reorganize messages for adding details

common/web/types/src/main.ts

@@ -23,8 +23,8 @@ export * as Constants from './consts/virtual-key-constants.js';
 
 export { defaultCompilerOptions, CompilerBaseOptions, CompilerCallbacks, CompilerOptions, CompilerEvent, CompilerErrorNamespace,
          CompilerErrorSeverity, CompilerPathCallbacks, CompilerFileSystemCallbacks, CompilerCallbackOptions,
-         CompilerError, CompilerMessageSpec, compilerErrorSeverity, CompilerErrorMask, CompilerFileCallbacks, compilerErrorSeverityName,
-         compilerExceptionToString, compilerErrorFormatCode,
+         CompilerError, CompilerMessageSpec, CompilerMessageSpecWithException, compilerErrorSeverity, CompilerErrorMask, CompilerFileCallbacks, compilerErrorSeverityName,
+         compilerErrorFormatCode, CompilerMessageDef,
          compilerLogLevelToSeverity, CompilerLogLevel, compilerEventFormat, ALL_COMPILER_LOG_LEVELS,
          ALL_COMPILER_LOG_FORMATS, CompilerLogFormat,
          CompilerMessageOverride,

common/web/types/src/util/common-events.ts

@@ -1,4 +1,4 @@
-import { CompilerErrorNamespace, CompilerErrorSeverity, CompilerMessageSpec as m } from './compiler-interfaces.js';
+import { CompilerErrorNamespace, CompilerErrorSeverity,  CompilerMessageDef as def, CompilerMessageSpec as m } from './compiler-interfaces.js';
 import { constants } from '@keymanapp/ldml-keyboard-constants';
 
 const CommonTypesErrMask   = CompilerErrorNamespace.CommonTypes;
@@ -10,37 +10,37 @@ const SevError = CompilerErrorSeverity.Error | CommonTypesErrMask;
 
 export class CommonTypesMessages {
   // structured Ajv validation error
-  static Error_SchemaValidationError = (o:{instancePath:string, keyword:string, message: string, params: string}) => m(this.ERROR_SchemaValidationError,
-    `Error validating LDML XML file: ${o.instancePath}: ${o.keyword}: ${o.message} ${o.params}`);
   static ERROR_SchemaValidationError = SevError | 0x0001;
+  static Error_SchemaValidationError = (o:{instancePath:string, keyword:string, message: string, params: string}) => m(this.ERROR_SchemaValidationError,
+    `Error validating LDML XML file: ${def(o.instancePath)}: ${def(o.keyword)}: ${def(o.message)} ${def(o.params)}`);
 
+  static ERROR_ImportInvalidBase = SevError | 0x0002;
   static Error_ImportInvalidBase = (o: { base: string, path: string, subtag: string }) =>
     m(this.ERROR_ImportInvalidBase,
-      `Import element with base ${o.base} is unsupported. Only ${constants.cldr_import_base} is supported.`);
-  static ERROR_ImportInvalidBase = SevError | 0x0002;
+      `Import element with base ${def(o.base)} is unsupported. Only ${constants.cldr_import_base} is supported.`);
 
+  static ERROR_ImportInvalidPath = SevError | 0x0003;
   static Error_ImportInvalidPath = (o: { base: string, path: string, subtag: string }) =>
     m(this.ERROR_ImportInvalidPath,
-      `Import element with invalid path ${o.path}: expected the form '${constants.cldr_version_latest}/*.xml`);
-  static ERROR_ImportInvalidPath = SevError | 0x0003;
+      `Import element with invalid path ${def(o.path)}: expected the form '${constants.cldr_version_latest}/*.xml`);
 
+  static ERROR_ImportReadFail = SevError | 0x0004;
   static Error_ImportReadFail = (o: { base: string, path: string, subtag: string }) =>
     m(this.ERROR_ImportReadFail,
-      `Import could not read data with path ${o.path}: expected the form '${constants.cldr_version_latest}/*.xml'`);
-  static ERROR_ImportReadFail = SevError | 0x0004;
+      `Import could not read data with path ${def(o.path)}: expected the form '${constants.cldr_version_latest}/*.xml'`);
 
+  static ERROR_ImportWrongRoot = SevError | 0x0005;
   static Error_ImportWrongRoot = (o: { base: string, path: string, subtag: string }) =>
     m(this.ERROR_ImportWrongRoot,
-      `Invalid import file ${o.path}: expected ${o.subtag} as root element.`);
-  static ERROR_ImportWrongRoot = SevError | 0x0005;
+      `Invalid import file ${def(o.path)}: expected ${def(o.subtag)} as root element.`);
 
+  static ERROR_ImportMergeFail = SevError | 0x0006;
   static Error_ImportMergeFail = (o: { base: string, path: string, subtag: string, subsubtag: string }) =>
     m(this.ERROR_ImportMergeFail,
-      `Problem importing ${o.path}: not sure how to handle non-array ${o.subtag}.${o.subsubtag}`);
-  static ERROR_ImportMergeFail = SevError | 0x0006;
+      `Problem importing ${def(o.path)}: not sure how to handle non-array ${def(o.subtag)}.${def(o.subsubtag)}`);
 
+  static ERROR_TestDataUnexpectedArray = SevError | 0x0007;
   static Error_TestDataUnexpectedArray = (o: {subtag: string}) =>
     m(this.ERROR_TestDataUnexpectedArray,
-      `Problem reading test data: expected single ${o.subtag} element, found multiple`);
-  static ERROR_TestDataUnexpectedArray = SevError | 0x0007;
+      `Problem reading test data: expected single ${def(o.subtag)} element, found multiple`);
 };

common/web/types/src/util/compiler-interfaces.ts

@@ -6,6 +6,11 @@ export interface CompilerEvent {
   line?: number;
   code: number;
   message: string;
+  /**
+   * detailed Markdown-formatted description of the error including
+   * references to documentation, remediation options.
+   */
+  detail?: string;
   /**
    * an internal error occurred that should be captured with a stack trace
    * e.g. to the Keyman sentry instance by kmc
@@ -524,25 +529,29 @@ export const defaultCompilerOptions: CompilerOptions = {
 
 /**
  * Convenience function for constructing CompilerEvents
- * @param code
- * @param message
+ * @param code     Unique numeric value of the event
+ * @param message  A short description of the error presented to the user
+ * @param detail   Detailed Markdown-formatted description of the error
+ *                 including references to documentation, remediation options.
  * @returns
  */
-export const CompilerMessageSpec = (code: number, message: string, exceptionVar?: any) : CompilerEvent => ({
+export const CompilerMessageSpec = (code: number, message: string, detail?: string) : CompilerEvent => ({
+  code,
+  message,
+  detail,
+});
+
+export const CompilerMessageDef = (param: any) => String(param ?? `<param>`);
+
+export const CompilerMessageSpecWithException = (code: number, message: string, exceptionVar: any, detail?: string) : CompilerEvent => ({
   code,
   message: exceptionVar
     ? (message ?? `Unexpected exception`) + `: ${exceptionVar.toString()}\n\nCall stack:\n${(exceptionVar instanceof Error ? exceptionVar.stack : (new Error()).stack)}` :
     message,
-  exceptionVar
+  detail,
+  exceptionVar,
 });
 
-/**
- * @deprecated use `CompilerError.exceptionToString` instead
- */
-export function compilerExceptionToString(e?: any) : string {
-  return CompilerError.exceptionToString(e);
-}
-
 /**
  * Compiler logging level and correspondence to severity
  */

developer/src/common/web/utils/src/osk.ts

@@ -37,8 +37,8 @@ export function parseMapping(mapping: any) {
     throw new Error(JSON.stringify((<any>SchemaValidators.default.displayMap).errors));
   }
 
-  let map: PuaMap = {};
-  for (let item of mapping.map) {
+  const map: PuaMap = {};
+  for (const item of mapping.map) {
     map[item.str] = String.fromCharCode(parseInt(item.pua, 16));
   }
   return map;
@@ -62,7 +62,7 @@ function remap(text: string, map: PuaMap) {
 
 export function remapVisualKeyboard(vk: VisualKeyboard.VisualKeyboard, map: PuaMap): boolean {
   let dirty = false;
-  for(let key of vk.keys) {
+  for(const key of vk.keys) {
     if(!key.text) {
       continue;
     }
@@ -92,18 +92,18 @@ export function remapTouchLayout(source: TouchLayout.TouchLayoutFile, map: PuaMa
     if(!platform) {
       return;
     }
-    for(let layer of platform.layer) {
-      for(let row of layer.row) {
-        for(let key of row.key) {
+    for(const layer of platform.layer) {
+      for(const row of layer.row) {
+        for(const key of row.key) {
           scanKey(key);
           let f: keyof TouchLayout.TouchLayoutFlick;
           for(f in key.flick ?? {}) {
             scanKey(key.flick[f]);
           }
-          for(let sk of key.sk ?? []) {
+          for(const sk of key.sk ?? []) {
             scanKey(sk);
           }
-          for(let mt of key.multitap ?? []) {
+          for(const mt of key.multitap ?? []) {
             scanKey(mt);
           }
         }

developer/src/kmc-analyze/src/messages.ts

@@ -1,4 +1,4 @@
-import { CompilerErrorNamespace, CompilerErrorSeverity, CompilerMessageSpec as m } from "@keymanapp/common-types";
+import { CompilerErrorNamespace, CompilerErrorSeverity, CompilerMessageSpec as m, CompilerMessageDef as def, CompilerMessageSpecWithException } from "@keymanapp/common-types";
 
 const Namespace = CompilerErrorNamespace.Analyzer;
 const SevInfo = CompilerErrorSeverity.Info | Namespace;
@@ -8,24 +8,24 @@ const SevInfo = CompilerErrorSeverity.Info | Namespace;
 const SevFatal = CompilerErrorSeverity.Fatal | Namespace;
 
 /**
- * @public
+ * @internal
  * Compiler messages for `kmc analyze`
  */
 export class AnalyzerMessages {
-  /** @internal */
-  static Fatal_UnexpectedException = (o:{e: any}) => m(this.FATAL_UnexpectedException, null, o.e ?? 'unknown error');
-  /**
-   * Raised when an analysis component has an internal error. If you
-   * experience this error, it should be reported to the Keyman team for
-   * resolution via https://github.com/keymanapp/keyman/issues/new
-   */
   static readonly FATAL_UnexpectedException = SevFatal | 0x0001;
+  static readonly Fatal_UnexpectedException = (o:{e: any}) => CompilerMessageSpecWithException(
+    this.FATAL_UnexpectedException,
+    null,
+    o.e ?? 'unknown error',
+    `Raised when an analysis components has an internal error. If you
+    experience this error, it should be reported to the Keyman team for
+    resolution via https://github.com/keymanapp/keyman/issues/new`
+  );
 
-  /** @internal */
-  static Info_ScanningFile = (o:{type: string, name: string}) => m(this.INFO_ScanningFile,
-    `Scanning ${o.type} file ${o.name}`);
-  /**
-   * Informative message reporting on the current file being scanned
-   */
   static readonly INFO_ScanningFile = SevInfo | 0x0002;
+  static readonly Info_ScanningFile = (o:{type: string, name: string}) => m(
+    this.INFO_ScanningFile,
+    `Scanning ${def(o.type)} file ${def(o.name)}`,
+    `Informative message reporting on the current file being scanned`
+  );
 };

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

@@ -1,4 +1,4 @@
-import { CompilerErrorNamespace, CompilerErrorSeverity, CompilerMessageSpec as m } from "@keymanapp/common-types";
+import { CompilerErrorNamespace, CompilerErrorSeverity, CompilerMessageSpec as m, CompilerMessageDef as def, CompilerMessageSpecWithException } from "@keymanapp/common-types";
 
 const Namespace = CompilerErrorNamespace.KeyboardInfoCompiler;
 // const SevInfo = CompilerErrorSeverity.Info | Namespace;
@@ -8,58 +8,58 @@ const SevError = CompilerErrorSeverity.Error | Namespace;
 const SevFatal = CompilerErrorSeverity.Fatal | Namespace;
 
 export class KeyboardInfoCompilerMessages {
-  static Fatal_UnexpectedException = (o:{e: any}) => m(this.FATAL_UnexpectedException, null, o.e ?? 'unknown error');
   static FATAL_UnexpectedException = SevFatal | 0x0001;
+  static Fatal_UnexpectedException = (o:{e: any}) => CompilerMessageSpecWithException(this.FATAL_UnexpectedException, null, o.e ?? 'unknown error');
 
-  static Error_FileDoesNotExist = (o:{filename: string}) => m(this.ERROR_FileDoesNotExist, `File ${o.filename} does not exist.`);
   static ERROR_FileDoesNotExist = SevError | 0x0002;
+  static Error_FileDoesNotExist = (o:{filename: string}) => m(this.ERROR_FileDoesNotExist, `File ${def(o.filename)} does not exist.`);
 
-  static Error_FileIsNotValid = (o:{filename: string; e: any}) => m(this.ERROR_FileIsNotValid,
-    `File ${o.filename} could not be parsed: ${(o.e ?? 'unknown error').toString()}.`);
   static ERROR_FileIsNotValid = SevError | 0x0003;
+  static Error_FileIsNotValid = (o:{filename: string; e: any}) => m(this.ERROR_FileIsNotValid,
+    `File ${def(o.filename)} could not be parsed: ${(o.e ?? 'unknown error').toString()}.`);
 
-  static Warn_MetadataFieldInconsistent = (o:{field:string, value:any, expected:any}) => m(this.WARN_MetadataFieldInconsistent,
-    `Warning: field ${o.field} value "${o.value}" does not match "${o.expected}" found in source file metadata.`);
   static WARN_MetadataFieldInconsistent = SevWarn | 0x0004;
+  static Warn_MetadataFieldInconsistent = (o:{field:string, value:any, expected:any}) => m(this.WARN_MetadataFieldInconsistent,
+    `Warning: field ${def(o.field)} value "${def(o.value)}" does not match "${def(o.expected)}" found in source file metadata.`);
 
-  static Error_InvalidAuthorEmail = (o:{email:string}) => m(this.ERROR_InvalidAuthorEmail,
-    `Invalid author email: ${o.email}`);
   static ERROR_InvalidAuthorEmail = SevError | 0x0005;
+  static Error_InvalidAuthorEmail = (o:{email:string}) => m(this.ERROR_InvalidAuthorEmail,
+    `Invalid author email: ${def(o.email)}`);
 
-  static Error_LicenseFileDoesNotExist = (o:{filename:string}) => m(this.ERROR_LicenseFileIsMissing,
-    `License file ${o.filename} does not exist.`);
   static ERROR_LicenseFileIsMissing = SevError | 0x0006;
+  static Error_LicenseFileDoesNotExist = (o:{filename:string}) => m(this.ERROR_LicenseFileIsMissing,
+    `License file ${def(o.filename)} does not exist.`);
 
-  static Error_LicenseFileIsDamaged = (o:{filename:string}) => m(this.ERROR_LicenseFileIsDamaged,
-    `License file ${o.filename} could not be loaded or decoded.`);
   static ERROR_LicenseFileIsDamaged = SevError | 0x0007;
+  static Error_LicenseFileIsDamaged = (o:{filename:string}) => m(this.ERROR_LicenseFileIsDamaged,
+    `License file ${def(o.filename)} could not be loaded or decoded.`);
 
-  static Error_LicenseIsNotValid = (o:{filename:string,message:string}) => m(this.ERROR_LicenseIsNotValid,
-    `An error was encountered parsing license file ${o.filename}: ${o.message}.`);
   static ERROR_LicenseIsNotValid = SevError | 0x0008;
+  static Error_LicenseIsNotValid = (o:{filename:string,message:string}) => m(this.ERROR_LicenseIsNotValid,
+    `An error was encountered parsing license file ${def(o.filename)}: ${def(o.message)}.`);
 
+  static ERROR_CannotBuildWithoutKmpFile = SevError | 0x0009;
   static Error_CannotBuildWithoutKmpFile = () => m(this.ERROR_CannotBuildWithoutKmpFile,
     `Compiling the .keyboard_info file requires a .kmp file for metadata.`);
-  static ERROR_CannotBuildWithoutKmpFile = SevError | 0x0009;
 
+  static ERROR_NoLicenseFound = SevError | 0x000A;
   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 Hint_OutputValidation = (o:{message: any}) => m(this.HINT_OutputValidation,
+    `Validating output: ${def(o.message)}.`);
 
-  static Warn_OutputValidation = (o:{message: any}) => m(this.WARN_OutputValidation,
-    `Validating output: ${o.message}.`);
   static WARN_OutputValidation = SevWarn | 0x000C;
+  static Warn_OutputValidation = (o:{message: any}) => m(this.WARN_OutputValidation,
+    `Validating output: ${def(o.message)}.`);
 
-  static Error_OutputValidation = (o:{message: any}) => m(this.ERROR_OutputValidation,
-    `Validating output: ${o.message}.`);
   static ERROR_OutputValidation = SevError | 0x000D;
+  static Error_OutputValidation = (o:{message: any}) => m(this.ERROR_OutputValidation,
+    `Validating output: ${def(o.message)}.`);
 
-  static Error_FontFileCannotBeRead = (o:{filename: string}) => m(this.ERROR_FontFileCannotBeRead,
-    `Font ${o.filename} could not be parsed to extract a font family.`);
   static ERROR_FontFileCannotBeRead = SevError | 0x000E;
+  static Error_FontFileCannotBeRead = (o:{filename: string}) => m(this.ERROR_FontFileCannotBeRead,
+    `Font ${def(o.filename)} could not be parsed to extract a font family.`);
 }