JMESPath evaluation

.changes/next-release/feature-dedce719f4dc02f94249c5b65ce4d54e508f1232.json

@@ -0,0 +1,7 @@
+{
+  "type": "feature",
+  "description": "Added a generic evaluator/interpreter for JMESPath expressions.",
+  "pull_requests": [
+    "[#2878](https://github.com/smithy-lang/smithy/pull/2878)"
+  ]
+}

settings.gradle.kts

@@ -26,6 +26,7 @@ include(":smithy-openapi-traits")
 include(":smithy-utils")
 include(":smithy-protocol-test-traits")
 include(":smithy-jmespath")
+include(":smithy-jmespath-tests")
 include(":smithy-waiters")
 include(":smithy-aws-cloudformation-traits")
 include(":smithy-aws-cloudformation")

smithy-jmespath-tests/build.gradle.kts

@@ -0,0 +1,24 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+plugins {
+    id("smithy.module-conventions")
+}
+
+description = "Compliance tests for JMESPath"
+
+extra["displayName"] = "Smithy :: JMESPath Tests"
+extra["moduleName"] = "software.amazon.smithy.jmespathtests"
+
+java {
+    sourceCompatibility = JavaVersion.VERSION_17
+    targetCompatibility = JavaVersion.VERSION_17
+}
+
+dependencies {
+    api(libs.junit.jupiter.api)
+    api(libs.junit.jupiter.params)
+    api(project(":smithy-jmespath"))
+    implementation(project(":smithy-utils"))
+}

smithy-jmespath-tests/src/main/java/software/amazon/smithy/jmespath/tests/ComplianceTestRunner.java

@@ -0,0 +1,152 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package software.amazon.smithy.jmespath.tests;
+
+import java.io.BufferedReader;
+import java.io.IOException;
+import java.io.InputStreamReader;
+import java.net.URL;
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.stream.Stream;
+import software.amazon.smithy.jmespath.JmespathException;
+import software.amazon.smithy.jmespath.JmespathExceptionType;
+import software.amazon.smithy.jmespath.JmespathExpression;
+import software.amazon.smithy.jmespath.RuntimeType;
+import software.amazon.smithy.jmespath.evaluation.Evaluator;
+import software.amazon.smithy.jmespath.evaluation.JmespathRuntime;
+import software.amazon.smithy.utils.IoUtils;
+
+public class ComplianceTestRunner<T> {
+    private static final String DEFAULT_TEST_CASE_LOCATION = "compliance";
+    private static final String SUBJECT_MEMBER = "given";
+    private static final String CASES_MEMBER = "cases";
+    private static final String COMMENT_MEMBER = "comment";
+    private static final String EXPRESSION_MEMBER = "expression";
+    private static final String RESULT_MEMBER = "result";
+    private static final String ERROR_MEMBER = "error";
+    private static final String BENCH_MEMBER = "bench";
+    private final JmespathRuntime<T> runtime;
+    private final List<TestCase<T>> testCases = new ArrayList<>();
+
+    private ComplianceTestRunner(JmespathRuntime<T> runtime) {
+        this.runtime = runtime;
+    }
+
+    public static <T> Stream<Object[]> defaultParameterizedTestSource(JmespathRuntime<T> runtime) {
+        ComplianceTestRunner<T> runner = new ComplianceTestRunner<>(runtime);
+        URL manifest = ComplianceTestRunner.class.getResource(DEFAULT_TEST_CASE_LOCATION + "/MANIFEST");
+        try (var reader = new BufferedReader(new InputStreamReader(manifest.openStream(), StandardCharsets.UTF_8))) {
+            reader.lines().forEach(line -> {
+                var url = ComplianceTestRunner.class.getResource(DEFAULT_TEST_CASE_LOCATION + "/" + line.trim());
+                runner.testCases.addAll(TestCase.from(url, runtime));
+            });
+        } catch (IOException e) {
+            throw new RuntimeException(e);
+        }
+        return runner.parameterizedTestSource();
+    }
+
+    public Stream<Object[]> parameterizedTestSource() {
+        return testCases.stream().map(testCase -> new Object[] {testCase.name(), testCase});
+    }
+
+    private record TestCase<T>(
+            JmespathRuntime<T> runtime,
+            String testSuite,
+            String comment,
+            T given,
+            String expression,
+            T expectedResult,
+            JmespathExceptionType expectedError,
+            String benchmark)
+            implements Runnable {
+        public static <T> List<TestCase<T>> from(URL url, JmespathRuntime<T> runtime) {
+            var path = url.getPath();
+            var testSuiteName = path.substring(path.lastIndexOf('/') + 1, path.lastIndexOf('.'));
+            var testCases = new ArrayList<TestCase<T>>();
+            String text = IoUtils.readUtf8Url(url);
+            T tests = JmespathExpression.parseJson(text, runtime);
+
+            for (var test : runtime.asIterable(tests)) {
+                var given = value(runtime, test, SUBJECT_MEMBER);
+                for (var testCase : runtime.asIterable(value(runtime, test, CASES_MEMBER))) {
+                    String comment = valueAsString(runtime, testCase, COMMENT_MEMBER);
+                    String expression = valueAsString(runtime, testCase, EXPRESSION_MEMBER);
+                    var result = value(runtime, testCase, RESULT_MEMBER);
+                    var expectedErrorString = valueAsString(runtime, testCase, ERROR_MEMBER);
+                    var expectedError =
+                            expectedErrorString != null ? JmespathExceptionType.fromID(expectedErrorString) : null;
+
+                    // Special case: The spec says function names cannot be quoted,
+                    // but our parser allows it, and this may be useful in the future.
+                    if ("function names cannot be quoted".equals(comment)) {
+                        expectedError = JmespathExceptionType.UNKNOWN_FUNCTION;
+                    } else if (expression.contains("\"to_string\"")) {
+                        expectedError = null;
+                        result = runtime.createString("1.0");
+                    }
+
+                    var benchmark = valueAsString(runtime, testCase, BENCH_MEMBER);
+                    testCases.add(new TestCase<>(runtime,
+                            testSuiteName,
+                            comment,
+                            given,
+                            expression,
+                            result,
+                            expectedError,
+                            benchmark));
+                }
+            }
+            return testCases;
+        }
+
+        private static <T> T value(JmespathRuntime<T> runtime, T object, String key) {
+            return runtime.value(object, runtime.createString(key));
+        }
+
+        private static <T> String valueAsString(JmespathRuntime<T> runtime, T object, String key) {
+            T result = runtime.value(object, runtime.createString(key));
+            return runtime.is(result, RuntimeType.NULL) ? null : runtime.asString(result);
+        }
+
+        private String name() {
+            return testSuite + (comment != null ? " - " + comment : "") + " (" + runtime.toString(given) + ")["
+                    + expression + "]";
+        }
+
+        @Override
+        public void run() {
+            try {
+                var parsed = JmespathExpression.parse(expression);
+                var result = new Evaluator<>(given, runtime).visit(parsed);
+                if (benchmark != null) {
+                    // Benchmarks don't include expected results or errors
+                    return;
+                }
+                if (expectedError != null) {
+                    throw new AssertionError("Expected " + expectedError + " error but no error occurred. \n"
+                            + "Actual:    " + runtime.toString(result) + "\n"
+                            + "For query: " + expression + "\n");
+                } else {
+                    if (!runtime.equal(expectedResult, result)) {
+                        throw new AssertionError("Expected does not match actual. \n"
+                                + "Expected:  " + runtime.toString(expectedResult) + "\n"
+                                + "Actual:    " + runtime.toString(result) + "\n"
+                                + "For query: " + expression + "\n");
+                    }
+                }
+            } catch (JmespathException e) {
+                if (!e.getType().equals(expectedError)) {
+                    throw new AssertionError("Expected error does not match actual error. \n"
+                            + "Expected: " + (expectedError != null ? expectedError : "(no error)") + "\n"
+                            + "Actual: " + e.getType() + " - " + e.getMessage() + "\n"
+                            + "For query: " + expression + "\n", e);
+                }
+            }
+        }
+    }
+}

smithy-jmespath-tests/src/main/resources/software/amazon/smithy/jmespath/tests/compliance/MANIFEST

@@ -0,0 +1,16 @@
+basic.json
+benchmarks.json
+boolean.json
+current.json
+escape.json
+filters.json
+functions.json
+identifiers.json
+indices.json
+literal.json
+multiselect.json
+pipe.json
+slice.json
+syntax.json
+unicode.json
+wildcard.json

smithy-jmespath-tests/src/main/resources/software/amazon/smithy/jmespath/tests/compliance/README.md

@@ -0,0 +1,8 @@
+# Compliance tests
+
+This directory is copied from this snapshot of the JMESPath compliance tests repository:
+
+https://github.com/jmespath/jmespath.test/tree/53abcc37901891cf4308fcd910eab287416c4609/tests
+
+The MANIFEST file is added so that these can be retrieved as resources
+(which don't support any notion of directories or listing).

smithy-jmespath-tests/src/main/resources/software/amazon/smithy/jmespath/tests/compliance/basic.json

@@ -0,0 +1,96 @@
+[{
+    "given":
+        {"foo": {"bar": {"baz": "correct"}}},
+     "cases": [
+         {
+            "expression": "foo",
+            "result": {"bar": {"baz": "correct"}}
+         },
+         {
+            "expression": "foo.bar",
+            "result": {"baz": "correct"}
+         },
+         {
+            "expression": "foo.bar.baz",
+            "result": "correct"
+         },
+         {
+            "expression": "foo\n.\nbar\n.baz",
+            "result": "correct"
+         },
+         {
+            "expression": "foo.bar.baz.bad",
+            "result": null
+         },
+         {
+            "expression": "foo.bar.bad",
+            "result": null
+         },
+         {
+            "expression": "foo.bad",
+            "result": null
+         },
+         {
+            "expression": "bad",
+            "result": null
+         },
+         {
+            "expression": "bad.morebad.morebad",
+            "result": null
+         }
+     ]
+},
+{
+    "given":
+        {"foo": {"bar": ["one", "two", "three"]}},
+    "cases": [
+         {
+            "expression": "foo",
+            "result": {"bar": ["one", "two", "three"]}
+         },
+         {
+            "expression": "foo.bar",
+            "result": ["one", "two", "three"]
+         }
+    ]
+},
+{
+    "given": ["one", "two", "three"],
+    "cases": [
+        {
+            "expression": "one",
+            "result": null
+        },
+        {
+            "expression": "two",
+            "result": null
+        },
+        {
+            "expression": "three",
+            "result": null
+        },
+        {
+            "expression": "one.two",
+            "result": null
+        }
+    ]
+},
+{
+    "given":
+        {"foo": {"1": ["one", "two", "three"], "-1": "bar"}},
+    "cases": [
+         {
+            "expression": "foo.\"1\"",
+            "result": ["one", "two", "three"]
+         },
+         {
+            "expression": "foo.\"1\"[0]",
+            "result": "one"
+         },
+         {
+            "expression": "foo.\"-1\"",
+            "result": "bar"
+         }
+    ]
+}
+]