content: Allow KaTeX parser to report failure reasons

Author: rajveermalviya

lib/model/content.dart

@@ -346,6 +346,8 @@ sealed class MathNode extends ContentNode {
     super.debugHtmlNode,
     required this.texSource,
     required this.nodes,
+    this.debugHardFailReason,
+    this.debugSoftFailReason,
   });
 
   final String texSource;
@@ -357,6 +359,9 @@ sealed class MathNode extends ContentNode {
   /// fallback instead.
   final List<KatexNode>? nodes;
 
+  final KatexParserHardFailReason? debugHardFailReason;
+  final KatexParserSoftFailReason? debugSoftFailReason;
+
   @override
   void debugFillProperties(DiagnosticPropertiesBuilder properties) {
     super.debugFillProperties(properties);
@@ -411,6 +416,8 @@ class MathBlockNode extends MathNode implements BlockContentNode {
     super.debugHtmlNode,
     required super.texSource,
     required super.nodes,
+    super.debugHardFailReason,
+    super.debugSoftFailReason,
   });
 }
 
@@ -880,6 +887,8 @@ class MathInlineNode extends MathNode implements InlineContentNode {
     super.debugHtmlNode,
     required super.texSource,
     required super.nodes,
+    super.debugHardFailReason,
+    super.debugSoftFailReason,
   });
 }
 
@@ -921,7 +930,9 @@ class _ZulipInlineContentParser {
     return MathInlineNode(
       texSource: parsed.texSource,
       nodes: parsed.nodes,
-      debugHtmlNode: debugHtmlNode);
+      debugHtmlNode: debugHtmlNode,
+      debugHardFailReason: kDebugMode ? parsed.hardFailReason : null,
+      debugSoftFailReason: kDebugMode ? parsed.softFailReason : null);
   }
 
   UserMentionNode? parseUserMention(dom.Element element) {
@@ -1628,7 +1639,9 @@ class _ZulipContentParser {
       result.add(MathBlockNode(
         texSource: parsed.texSource,
         nodes: parsed.nodes,
-        debugHtmlNode: kDebugMode ? firstChild : null));
+        debugHtmlNode: kDebugMode ? firstChild : null,
+        debugHardFailReason: kDebugMode ? parsed.hardFailReason : null,
+        debugSoftFailReason: kDebugMode ? parsed.softFailReason : null));
     } else {
       result.add(UnimplementedBlockContentNode(htmlNode: firstChild));
     }
@@ -1664,7 +1677,9 @@ class _ZulipContentParser {
           result.add(MathBlockNode(
             texSource: parsed.texSource,
             nodes: parsed.nodes,
-            debugHtmlNode: debugHtmlNode));
+            debugHtmlNode: debugHtmlNode,
+            debugHardFailReason: kDebugMode ? parsed.hardFailReason : null,
+            debugSoftFailReason: kDebugMode ? parsed.softFailReason : null));
           continue;
         }
       }

lib/model/katex.dart

@@ -8,10 +8,40 @@ import 'binding.dart';
 import 'content.dart';
 import 'settings.dart';
 
+/// The failure reason in case the KaTeX parser encountered a
+/// `_KatexHtmlParseError` exception.
+///
+/// Generally this means that parser encountered an unexpected HTML structure,
+/// an unsupported HTML node, or an unexpected inline CSS style or CSS class on
+/// a specific node.
+class KatexParserHardFailReason {
+  const KatexParserHardFailReason({
+    required this.error,
+    required this.stackTrace,
+  });
+
+  final String error;
+  final StackTrace stackTrace;
+}
+
+/// The failure reason in case the KaTeX parser found an unsupported
+/// CSS class or unsupported inline CSS style property.
+class KatexParserSoftFailReason {
+  const KatexParserSoftFailReason({
+    this.unsupportedCssClasses = const [],
+    this.unsupportedInlineCssProperties = const [],
+  });
+
+  final List<String> unsupportedCssClasses;
+  final List<String> unsupportedInlineCssProperties;
+}
+
 class MathParserResult {
   const MathParserResult({
     required this.texSource,
     required this.nodes,
+    this.hardFailReason,
+    this.softFailReason,
   });
 
   final String texSource;
@@ -22,6 +52,9 @@ class MathParserResult {
   /// CSS style, indicating that the widget should render the [texSource] as a
   /// fallback instead.
   final List<KatexNode>? nodes;
+
+  final KatexParserHardFailReason? hardFailReason;
+  final KatexParserSoftFailReason? softFailReason;
 }
 
 /// Parses the HTML spans containing KaTeX HTML tree.
@@ -87,21 +120,33 @@ MathParserResult? parseMath(dom.Element element, { required bool block }) {
     final flagForceRenderKatex =
       globalSettings.getBool(BoolGlobalSetting.forceRenderKatex);
 
+    KatexParserHardFailReason? hardFailReason;
+    KatexParserSoftFailReason? softFailReason;
     List<KatexNode>? nodes;
     if (flagRenderKatex) {
       final parser = _KatexParser();
       try {
         nodes = parser.parseKatexHtml(katexHtmlElement);
       } on _KatexHtmlParseError catch (e, st) {
         assert(debugLog('$e\n$st'));
+        hardFailReason = KatexParserHardFailReason(
+          error: e.message ?? 'unknown',
+          stackTrace: st);
       }
 
       if (parser.hasError && !flagForceRenderKatex) {
         nodes = null;
+        softFailReason = KatexParserSoftFailReason(
+          unsupportedCssClasses: parser.unsupportedCssClasses,
+          unsupportedInlineCssProperties: parser.unsupportedInlineCssProperties);
       }
     }
 
-    return MathParserResult(nodes: nodes, texSource: texSource);
+    return MathParserResult(
+      nodes: nodes,
+      texSource: texSource,
+      hardFailReason: hardFailReason,
+      softFailReason: softFailReason);
   } else {
     return null;
   }
@@ -111,6 +156,9 @@ class _KatexParser {
   bool get hasError => _hasError;
   bool _hasError = false;
 
+  final unsupportedCssClasses = <String>[];
+  final unsupportedInlineCssProperties = <String>[];
+
   List<KatexNode> parseKatexHtml(dom.Element element) {
     assert(element.localName == 'span');
     assert(element.className == 'katex-html');
@@ -122,7 +170,10 @@ class _KatexParser {
       if (node case dom.Element(localName: 'span')) {
         return _parseSpan(node);
       } else {
-        throw _KatexHtmlParseError();
+        throw _KatexHtmlParseError(
+          node is dom.Element
+            ? 'unsupported html node: ${node.localName}'
+            : 'unsupported html node');
       }
     }));
   }
@@ -357,6 +408,7 @@ class _KatexParser {
 
         default:
           assert(debugLog('KaTeX: Unsupported CSS class: $spanClass'));
+          unsupportedCssClasses.add(spanClass);
           _hasError = true;
       }
     }
@@ -410,6 +462,7 @@ class _KatexParser {
             // TODO handle more CSS properties
             assert(debugLog('KaTeX: Unsupported CSS expression:'
               ' ${expression.toDebugString()}'));
+            unsupportedInlineCssProperties.add(property);
             _hasError = true;
           } else {
             throw _KatexHtmlParseError();