Merge pull request #111 from Peefy/feat-more-java-api-and-docs

feat: add all Java API tests and reference docs

java/src/main/java/com/kcl/api/Service.java

@@ -24,6 +24,9 @@ public interface Service {
     // List all the variables in the KCL file
     ListVariables_Result listVariables(ListVariables_Args args) throws Exception;
 
+    // List all the option functions in the KCL file
+    ListOptions_Result listOptions(ParseProgram_Args args) throws Exception;
+
     // Service for getting the full schema type list
     GetSchemaTypeMapping_Result getSchemaTypeMapping(GetSchemaTypeMapping_Args args) throws Exception;
 
@@ -53,4 +56,7 @@ public interface Service {
 
     // Service for the dependency updating
     UpdateDependencies_Result updateDependencies(UpdateDependencies_Args args) throws Exception;
+
+    // Service for the KCL service version information.
+    GetVersion_Result getVersion(GetVersion_Args args) throws Exception;
 }

java/src/test/java/com/kcl/ExecProgramTest.java

@@ -0,0 +1,22 @@
+package com.kcl;
+
+import com.kcl.api.API;
+import com.kcl.api.Spec.ExecProgram_Args;
+import com.kcl.api.Spec.ExecProgram_Result;
+
+import org.junit.Assert;
+import org.junit.Test;
+
+public class ExecProgramTest {
+
+    private static final String TEST_FILE = "./src/test_data/schema.k";
+
+    @Test
+    public void testGetSchemaTypeApi() throws Exception {
+        ExecProgram_Args args = ExecProgram_Args.newBuilder().addKFilenameList(TEST_FILE).build();
+
+        API apiInstance = new API();
+        ExecProgram_Result result = apiInstance.execProgram(args);
+        Assert.assertEquals(result.getYamlResult(), "app:\n" + "  replicas: 2");
+    }
+}

java/src/test/java/com/kcl/FormatTest.java

@@ -0,0 +1,35 @@
+package com.kcl;
+
+import com.kcl.api.API;
+import com.kcl.api.Spec.FormatCode_Args;
+import com.kcl.api.Spec.FormatCode_Result;
+import com.kcl.api.Spec.FormatPath_Args;
+import com.kcl.api.Spec.FormatPath_Result;
+import org.junit.Assert;
+import org.junit.Test;
+
+public class FormatTest {
+    @Test
+    public void testFormatPathApi() throws Exception {
+        final String TEST_PATH = "./src/test_data/format_path/test.k";
+        FormatPath_Args args = FormatPath_Args.newBuilder().setPath(TEST_PATH).build();
+        API apiInstance = new API();
+        apiInstance.formatPath(args);
+    }
+
+    @Test
+    public void testFormatCodeApi() throws Exception {
+        String sourceCode = "schema Person:\n" + "    name:   str\n" + "    age:    int\n" + "    check:\n"
+                + "        0 <   age <   120\n";
+
+        FormatCode_Args args = FormatCode_Args.newBuilder().setSource(sourceCode).build();
+
+        API apiInstance = new API();
+        FormatCode_Result result = apiInstance.formatCode(args);
+
+        String expectedFormattedCode = "schema Person:\n" + "    name: str\n" + "    age: int\n\n" + "    check:\n"
+                + "        0 < age < 120\n\n";
+
+        Assert.assertEquals(expectedFormattedCode, result.getFormatted().toStringUtf8());
+    }
+}

java/src/test/java/com/kcl/GetSchemaTypeTest.java

@@ -0,0 +1,29 @@
+package com.kcl;
+
+import com.kcl.api.API;
+import com.kcl.api.Spec.ExecProgram_Args;
+import com.kcl.api.Spec.GetSchemaTypeMapping_Args;
+import com.kcl.api.Spec.GetSchemaTypeMapping_Result;
+import com.kcl.api.Spec.KclType;
+
+import org.junit.Assert;
+import org.junit.Test;
+
+public class GetSchemaTypeTest {
+
+    private static final String TEST_FILE = "./src/test_data/schema.k";
+
+    @Test
+    public void testGetSchemaTypeApi() throws Exception {
+        ExecProgram_Args execArgs = ExecProgram_Args.newBuilder().addKFilenameList(TEST_FILE).build();
+
+        GetSchemaTypeMapping_Args args = GetSchemaTypeMapping_Args.newBuilder().setExecArgs(execArgs).build();
+
+        API apiInstance = new API();
+        GetSchemaTypeMapping_Result result = apiInstance.getSchemaTypeMapping(args);
+
+        KclType appSchemaType = result.getSchemaTypeMappingMap().get("app");
+        String replicasType = appSchemaType.getPropertiesOrThrow("replicas").getType();
+        Assert.assertEquals("int", replicasType);
+    }
+}

java/src/test/java/com/kcl/GetVersionTest.java

@@ -0,0 +1,20 @@
+package com.kcl;
+
+import org.junit.Assert;
+import org.junit.Test;
+
+import com.kcl.api.API;
+import com.kcl.api.Spec.GetVersion_Args;
+import com.kcl.api.Spec.GetVersion_Result;
+
+public class GetVersionTest {
+    @Test
+    public void testGetVersion() throws Exception {
+        API api = new API();
+        GetVersion_Args version_args = GetVersion_Args.newBuilder().build();
+        GetVersion_Result result = api.getVersion(version_args);
+        String versionInfo = result.getVersionInfo();
+        Assert.assertTrue(versionInfo, versionInfo.contains("Version"));
+        Assert.assertTrue(versionInfo, versionInfo.contains("GitCommit"));
+    }
+}

java/src/test/java/com/kcl/LintTest.java

@@ -0,0 +1,22 @@
+package com.kcl;
+
+import com.kcl.api.API;
+import com.kcl.api.Spec.LintPath_Args;
+import com.kcl.api.Spec.LintPath_Result;
+import org.junit.Assert;
+import org.junit.Test;
+
+public class LintTest {
+    @Test
+    public void testLintPathApi() throws Exception {
+        final String TEST_PATH = "./src/test_data/lint_path/test-lint.k";
+
+        LintPath_Args args = LintPath_Args.newBuilder().addPaths(TEST_PATH).build();
+
+        API apiInstance = new API();
+        LintPath_Result result = apiInstance.lintPath(args);
+        boolean foundWarning = result.getResultsList().stream()
+                .anyMatch(warning -> warning.contains("Module 'math' imported but unused"));
+        Assert.assertTrue("Expected warning not found", foundWarning);
+    }
+}

java/src/test/java/com/kcl/ListOptionsTest.java

@@ -0,0 +1,21 @@
+package com.kcl;
+
+import org.junit.Assert;
+import org.junit.Test;
+
+import com.kcl.api.API;
+import com.kcl.api.Spec.ParseProgram_Args;
+import com.kcl.api.Spec.ListOptions_Result;
+
+public class ListOptionsTest {
+    @Test
+    public void testParseProgram() throws Exception {
+        ParseProgram_Args args = ParseProgram_Args.newBuilder().addPaths("./src/test_data/option/main.k").build();
+
+        API apiInstance = new API();
+        ListOptions_Result result = apiInstance.listOptions(args);
+        Assert.assertEquals(result.getOptions(0).getName(), "key1");
+        Assert.assertEquals(result.getOptions(1).getName(), "key2");
+        Assert.assertEquals(result.getOptions(2).getName(), "metadata-key");
+    }
+}

java/src/test/java/com/kcl/LoadSettingsFileTest.java

@@ -0,0 +1,22 @@
+package com.kcl;
+
+import org.junit.Assert;
+import org.junit.Test;
+
+import com.kcl.api.API;
+import com.kcl.api.Spec.LoadSettingsFiles_Args;
+import com.kcl.api.Spec.LoadSettingsFiles_Result;
+
+public class LoadSettingsFileTest {
+    @Test
+    public void testLoadSettingsFile() throws Exception {
+        API api = new API();
+        LoadSettingsFiles_Args args = LoadSettingsFiles_Args.newBuilder().addFiles("./src/test_data/settings/kcl.yaml")
+                .build();
+        LoadSettingsFiles_Result result = api.loadSettingsFiles(args);
+        Assert.assertEquals(result.getKclCliConfigs().getFilesCount(), 0);
+        Assert.assertEquals(result.getKclCliConfigs().getStrictRangeCheck(), true);
+        Assert.assertEquals(result.getKclOptions(0).getKey(), "key");
+        Assert.assertEquals(result.getKclOptions(0).getValue(), "\"value\"");
+    }
+}

java/src/test/java/com/kcl/ParseTest.java

@@ -0,0 +1,20 @@
+package com.kcl;
+
+import org.junit.Assert;
+import org.junit.Test;
+
+import com.kcl.api.API;
+import com.kcl.api.Spec.ParseFile_Args;
+import com.kcl.api.Spec.ParseFile_Result;
+
+public class ParseTest {
+    @Test
+    public void testParseFile() throws Exception {
+        ParseFile_Args args = ParseFile_Args.newBuilder().setPath("./src/test_data/parse/main.k").build();
+
+        API apiInstance = new API();
+        ParseFile_Result result = apiInstance.parseFile(args);
+        Assert.assertNotNull(result.getAstJson());
+        Assert.assertEquals(result.getDepsCount(), 2);
+    }
+}

java/src/test/java/com/kcl/RenameTest.java

@@ -0,0 +1,40 @@
+package com.kcl;
+
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Paths;
+
+import org.junit.Assert;
+import org.junit.Test;
+
+import com.kcl.api.API;
+import com.kcl.api.Spec.RenameCode_Args;
+import com.kcl.api.Spec.RenameCode_Result;
+import com.kcl.api.Spec.Rename_Args;
+import com.kcl.api.Spec.Rename_Result;
+
+public class RenameTest {
+    @Test
+    public void testRenameCode() throws Exception {
+        API api = new API();
+        RenameCode_Args args = RenameCode_Args.newBuilder().setPackageRoot("/mock/path").setSymbolPath("a")
+                .putSourceCodes("/mock/path/main.k", "a = 1\nb = a").setNewName("a2").build();
+        RenameCode_Result result = api.renameCode(args);
+        Assert.assertEquals(result.getChangedCodesOrThrow("/mock/path/main.k"), "a2 = 1\nb = a2");
+    }
+
+    @Test
+    public void testRename() throws Exception {
+        String backupContent = new String(Files.readAllBytes(Paths.get("./src/test_data/rename/main.bak")),
+                StandardCharsets.UTF_8);
+        Files.write(Paths.get("./src/test_data/rename/main.k"), backupContent.getBytes(StandardCharsets.UTF_8));
+
+        Rename_Args args = Rename_Args.newBuilder().setPackageRoot("./src/test_data/rename").setSymbolPath("a")
+                .addFilePaths("./src/test_data/rename/main.k").setNewName("a2").build();
+
+        API apiInstance = new API();
+        Rename_Result result = apiInstance.rename(args);
+
+        Assert.assertTrue(result.getChangedFiles(0), result.getChangedFiles(0).contains("main.k"));
+    }
+}

java/src/test/java/com/kcl/TestingTest.java

@@ -0,0 +1,18 @@
+package com.kcl;
+
+import com.kcl.api.API;
+import com.kcl.api.Spec.Test_Args;
+import com.kcl.api.Spec.Test_Result;
+
+import org.junit.Assert;
+import org.junit.Test;
+
+public class TestingTest {
+    @Test
+    public void testLintPathApi() throws Exception {
+        API apiInstance = new API();
+        Test_Args args = Test_Args.newBuilder().addPkgList("./src/test_data/testing/...").build();
+        Test_Result result = apiInstance.test(args);
+        Assert.assertEquals(result.getInfoCount(), 2);
+    }
+}

java/src/test/java/com/kcl/UpdateDependenciesTest.java

@@ -1,6 +1,8 @@
 package com.kcl;
 
 import com.kcl.api.API;
+import com.kcl.api.Spec.ExecProgram_Args;
+import com.kcl.api.Spec.ExecProgram_Result;
 import com.kcl.api.Spec.UpdateDependencies_Args;
 import com.kcl.api.Spec.UpdateDependencies_Result;
 
@@ -17,4 +19,20 @@ public void testUpdateDependencies() throws Exception {
                 UpdateDependencies_Args.newBuilder().setManifestPath("./src/test_data/update_dependencies").build());
         Assert.assertEquals(result.getExternalPkgsCount(), 2);
     }
+
+    @Test
+    public void testExecProgramWithExternalDependencies() throws Exception {
+        // API instance
+        API api = new API();
+
+        UpdateDependencies_Result result = api.updateDependencies(
+                UpdateDependencies_Args.newBuilder().setManifestPath("./src/test_data/update_dependencies").build());
+        Assert.assertEquals(result.getExternalPkgsCount(), 2);
+
+        ExecProgram_Args execArgs = ExecProgram_Args.newBuilder().addAllExternalPkgs(result.getExternalPkgsList())
+                .addKFilenameList("./src/test_data/update_dependencies/main.k").build();
+
+        ExecProgram_Result execResult = api.execProgram(execArgs);
+        Assert.assertEquals(execResult.getYamlResult(), "a: Hello World!");
+    }
 }

java/src/test/java/com/kcl/ValidateTest.java

@@ -0,0 +1,25 @@
+package com.kcl;
+
+import org.junit.Assert;
+import org.junit.Test;
+
+import com.kcl.api.API;
+import com.kcl.api.Spec.ValidateCode_Args;
+import com.kcl.api.Spec.ValidateCode_Result;
+
+public class ValidateTest {
+    @Test
+    public void testValidateCodeApi() throws Exception {
+        String code = "schema Person:\n" + "    name: str\n" + "    age: int\n" + "    check:\n"
+                + "        0 < age < 120\n";
+
+        String data = "{\"name\": \"Alice\", \"age\": 10}";
+
+        ValidateCode_Args args = ValidateCode_Args.newBuilder().setCode(code).setData(data).setFormat("json").build();
+        API apiInstance = new API();
+        ValidateCode_Result result = apiInstance.validateCode(args);
+
+        Assert.assertTrue(result.getSuccess());
+        Assert.assertEquals("", result.getErrMessage());
+    }
+}

java/src/test_data/format_path/test.k

@@ -0,0 +1 @@
+a = 1

java/src/test_data/get_schema_ty/aaa/kcl.mod

@@ -0,0 +1,5 @@
+[package]
+name = "aaa"
+edition = "0.0.1"
+version = "0.0.1"
+

java/src/test_data/get_schema_ty/aaa/main.k

@@ -0,0 +1,10 @@
+import bbb as b
+import ccc as c
+
+a = b.B {
+    name: "b instance in a"
+}
+
+a_c = c.C {
+    name: "c instance in a"
+}

java/src/test_data/get_schema_ty/bbb/kcl.mod

@@ -0,0 +1,5 @@
+[package]
+name = "bbb"
+edition = "0.0.1"
+version = "0.0.1"
+

java/src/test_data/get_schema_ty/bbb/main.k

@@ -0,0 +1,2 @@
+schema B:
+    name: str

java/src/test_data/get_schema_ty/ccc/kcl.mod

@@ -0,0 +1,5 @@
+[package]
+name = "ccc"
+edition = "0.0.1"
+version = "0.0.1"
+

java/src/test_data/get_schema_ty/ccc/main.k

@@ -0,0 +1,2 @@
+schema C:
+    name: str

java/src/test_data/lint_path/test-lint.k

@@ -0,0 +1,3 @@
+import math
+
+a = 1

java/src/test_data/option/main.k

@@ -0,0 +1,5 @@
+a = option("key1")
+b = option("key2", required=True)
+c = {
+    metadata.key = option("metadata-key")
+}

java/src/test_data/parse/main.k

@@ -0,0 +1,5 @@
+import pkg1
+import pkg2
+
+a1 = pkg1.a
+a2 = pkg2.a

java/src/test_data/parse/pkg1/pkg.k

@@ -0,0 +1 @@
+a = 1

java/src/test_data/parse/pkg2/pkg.k

@@ -0,0 +1 @@
+a = 1

java/src/test_data/rename/main.bak

@@ -0,0 +1,2 @@
+a = 1
+b = a