Fix part of #4044: Add protos & testing library for commutative expre…

…ssions/operations (#4049)

## Explanation
Fix part of #4044
Originally copied from #2173 when it was in proof-of-concept form

This PR introduces the proto & Truth subject for representing math expressions in a way that makes them trivial to compare without commutative or associativity changing the meaning of the operation. See #4047 for details about the test exemptions being made here, and the custom Kotlin DSL. Note that #4098 is tracking adding tests for the new test subject.

The way the structure introduced here works is that it provides a structure for math expressions that collects "accumulations" (i.e. products or summations). Since both multiplication and addition are commutative operators, elements of these accumulation lists can be rearranged (and thus sorted for deterministic sorting that doesn't fail upon commutative reordering). Associativity complicates this since we actually want expressions like 3-4+7 to be equivalent to 7+3-4. In order for that to be the case, the structure treats subtraction as negative addition and division as inverted multiplication so that division and subtraction terms can also be rearranged. This leaves only square roots & exponentiations as non-commutative operations (which are more or less retained in the same hierarchical structure as math expressions).

This structure will be utilized in a later PR when a routine for converting ``MathExpression``s to ``ComparableOperation``s, and then later in MatchesUpToTrivialManipulations classifier implementations for each numeric expression, algebraic expression, and math equation interaction. For specific details on this classifier, see [the PRD](https://docs.google.com/document/d/1x2vcSjocJUXkwwlce5Gjjq_Z83ykVIn2Fp0BcnrOrTg/edit#heading=h.g0bd549g079d).

## Essential Checklist
- [x] The PR title and explanation each start with "Fix #bugnum: " (If this PR fixes part of an issue, prefix the title with "Fix part of #bugnum: ...".)
- [x] Any changes to [scripts/assets](https://github.com/oppia/oppia-android/tree/develop/scripts/assets) files have their rationale included in the PR explanation.
- [x] The PR follows the [style guide](https://github.com/oppia/oppia-android/wiki/Coding-style-guide).
- [x] The PR does not contain any unnecessary code changes from Android Studio ([reference](https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR#undo-unnecessary-changes)).
- [x] The PR is made from a branch that's **not** called "develop" and is up-to-date with "develop".
- [x] The PR is **assigned** to the appropriate reviewers ([reference](https://github.com/oppia/oppia-android/wiki/Guidance-on-submitting-a-PR#clarification-regarding-assignees-and-reviewers-section)).

## For UI-specific PRs only
N/A -- proto & testing library only change, and the proto changes are only additions. No UI functionality is yet affected by these changes.

Commit history:

* Copy proto-based changes from #2173.

* Introduce math.proto & refactor math extensions.

Much of this is copied from #2173.

* Migrate tests & remove unneeded prefix.

* Add needed newline.

* Some needed Fraction changes.

* Introduce math expression + equation protos.

Also adds testing libraries for both + fractions & reals (new
structure).

Most of this is copied from #2173.

* Add protos + testing lib for commutative exprs.

* Lint fix.

* Fix broken test post-refactor.

* Post-merge fix.

* Add regex check, docs, and resolve TODOs.

This also changes regex handling in the check to be more generic for
better flexibility when matching files.

* Lint fix.

* Fix failing static checks.

* Fix broken CI checks.

Adds missing KDocs, test file exemptions, and fixes the Gradle build.

* Lint fixes.

* Add docs & exempted tests.

* Remove blank line.

* Address reviewer comments + other stuff.

This also fixes a typo and incorrectly ordered exemptions list I noticed
during development of downstream PRs.

* Move StringExtensions & fraction parsing.

This splits fraction parsing between UI & utility components.

* Add missing KDocs.

* Remove the ComparableOperationList wrapper.

* Fix broken build.

* Fix broken build post-merge.

* Post-merge fix.

* More post-merge fixes.

model/src/main/proto/math.proto

@@ -188,3 +188,98 @@ message MathEquation {
   // The MathExpression representing the left-hand side of the equation, e.g. the '0' in 2x+3y=0.
   MathExpression right_side = 2;
 }
+
+// An operation that can be compared in a way that does not change the value based on commutativity
+// or associativity.
+//
+// 'Comparable' here means that this structure provides a trivial way to compare commutative and
+// associative operations (i.e. by extracting terms from multiple subsequent commutative &
+// associative operations into lists that can be deterministically sorted). This structure is meant
+// to provide a means to compare two expressions without considering associativity or commutativity
+// (though the latter requires the operation lists stored within this structure to be sorted before
+// using standard proto equals checking). Also note that care must be taken when performing equality
+// checking since this structure can contain floating point values that require an epsilon check to
+// approximate equality.
+message ComparableOperation {
+  // Indicates that this operation (e.g. x) should be treated as negated (e.g. -x).
+  bool is_negated = 1;
+
+  // Indicates that this operation (e.g. x) should be treated as a multiplicative inverse
+  // (e.g. 1/x).
+  bool is_inverted = 2;
+
+  // The supported comparison types.
+  oneof comparison_type {
+    // Indicates that this operation is a commutative accumulation (that is, a list of subsequent
+    // operations of the same type that are commutative, e.g. addition or multiplication).
+    CommutativeAccumulation commutative_accumulation = 3;
+
+    // Indicates that this operation is a non-commutative operation and thus cannot be
+    // accumulated (e.g. exponentiation).
+    NonCommutativeOperation non_commutative_operation = 4;
+
+    // Indicates that this operation represents a constant value.
+    Real constant_term = 5;
+
+    // Indicates that this operation represents a variable.
+    string variable_term = 6;
+  }
+
+  // Represents an accumulation of operations (such as a summation or product).
+  //
+  // This helps simplify comparison across commutative and associative boundaries by collecting
+  // terms into sortable lists, such as the expression 1+2+3 becoming [1,2,3] and trivially
+  // comparable to [3,2,1] from 3+2+1 (once sorted).
+  //
+  // Subsequent subtractions are treated as additions with each term arithmetically negated (i.e.
+  // f(x)=-x). Similarly, divisions are considered multiplications with each divisor being
+  // multiplicatively inverted (i.e. the reciprocal function: f(x)=1/x).
+  message CommutativeAccumulation {
+    // The types of supported accumulations.
+    enum AccumulationType {
+      // Represents an unsupported accumulation type (which is always invalid).
+      ACCUMULATION_TYPE_UNSPECIFIED = 0;
+
+      // Represents an accumulation of sums, e.g. 1+2+3.
+      SUMMATION = 1;
+
+      // Represents an accumulation of products, e.g. 2*3*4.
+      PRODUCT = 2;
+    }
+
+    // The type of this accumulation.
+    AccumulationType accumulation_type = 1;
+
+    // The list of operations being combined in this accumulation (which can be subsequent
+    // accumulations in more complex expressions).
+    repeated ComparableOperation combined_operations = 2;
+  }
+
+  // Represents a non-commutative operation (such as exponentiation or square roots).
+  //
+  // Operations represented by this structure cannot be combined in an accumulation which means they
+  // can't be "internally" sorted (in order to maintain the commutativity and associativity of the
+  // operation).
+  message NonCommutativeOperation {
+    // The types of supported non-commutative operations.
+    oneof operation_type {
+      // Indicates that this is an exponentiation operation.
+      BinaryOperation exponentiation = 1;
+
+      // Indicates that this is a square root operation with this operation representing the
+      // argument passed to the square root function.
+      ComparableOperation square_root = 2;
+    }
+
+    // Represents a non-commutative binary operation, such as exponentiation.
+    message BinaryOperation {
+      // The left-hand side of the operation (which itself is another operation), e.g. the '2' in
+      // 2^3.
+      ComparableOperation left_operand = 1;
+
+      // The right-hand side of the operation (which itself is another operation), e.g. the '3' in
+      // 2^3.
+      ComparableOperation right_operand = 2;
+    }
+  }
+}

scripts/assets/test_file_exemptions.textproto

@@ -648,6 +648,7 @@ exempted_file_path: "testing/src/main/java/org/oppia/android/testing/espresso/Ge
 exempted_file_path: "testing/src/main/java/org/oppia/android/testing/espresso/ImageViewMatcher.kt"
 exempted_file_path: "testing/src/main/java/org/oppia/android/testing/espresso/KonfettiViewMatcher.kt"
 exempted_file_path: "testing/src/main/java/org/oppia/android/testing/junit/DefineAppLanguageLocaleContext.kt"
+exempted_file_path: "testing/src/main/java/org/oppia/android/testing/math/ComparableOperationSubject.kt"
 exempted_file_path: "testing/src/main/java/org/oppia/android/testing/math/FractionSubject.kt"
 exempted_file_path: "testing/src/main/java/org/oppia/android/testing/math/MathEquationSubject.kt"
 exempted_file_path: "testing/src/main/java/org/oppia/android/testing/math/MathExpressionSubject.kt"

testing/src/main/java/org/oppia/android/testing/math/BUILD.bazel

@@ -6,6 +6,23 @@ load("@io_bazel_rules_kotlin//kotlin:kotlin.bzl", "kt_android_library")
 
 # TODO(#2747): Move these libraries to be under utility/.../math/testing.
 
+kt_android_library(
+    name = "comparable_operation_subject",
+    testonly = True,
+    srcs = [
+        "ComparableOperationSubject.kt",
+    ],
+    visibility = [
+        "//:oppia_testing_visibility",
+    ],
+    deps = [
+        ":real_subject",
+        "//model/src/main/proto:math_java_proto_lite",
+        "//third_party:com_google_truth_extensions_truth-liteproto-extension",
+        "//third_party:com_google_truth_truth",
+    ],
+)
+
 kt_android_library(
     name = "fraction_subject",
     testonly = True,