1 logging and exception review (#46)

cuzfrog · web-flow · commit 35fb83ec32bd · 2024-11-05T20:42:21.000+08:00
* Refine ap logging
* Refine exception and messages
diff --git a/README.md b/README.md
@@ -1,23 +1,53 @@
 [![CI](https://github.com/cuzfrog/sharedtype/actions/workflows/ci.yaml/badge.svg)](https://github.com/cuzfrog/sharedtype/actions/workflows/ci.yaml)
 # SharedType - Sharing Java Types made easy
+From Java:
+```java
+@SharedType
+record User(String name, int age, String email) {}
+```
+To Typescript:
+```typescript
+export interface User {
+    name: string;
+    age: number;
+    email: string;
+}
+```
+Go (Planed):
+```golang
+type User struct {
+    Name string
+    Age int
+    Email string
+}
+```
+Rust (Planed):
+```rust
+struct User {
+    name: String,
+    age: i32,
+    email: String,
+}
+```
+And more.
 
-* Client Java version >= 8.
-* Only client source dependency is `@SharedType`.
-* SharedType annotation processor jar is <100KB, only 2 small dependencies: jsr305 annotations and mustache.
-* Parsing takes milliseconds. See [Performance](doc/Performance.md).
-* Put `@SharedType` and there you go.
-* Global + class level options.
-* (Not Implemented) Compile time resolvable values. E.g. constant literals.
-* Generics and complex type structures.
-* (Only TS Implemented) Multiple target schemas, extendable.
+## Features
+* Java8 full support. No hassles.
+* Client source dependency is only `@SharedType`. Nothing gets into bytecode/runtime.
+* SharedType AP jars <100KB, only 2 small dependencies: jsr305 annotations and mustache. Download less.
+* Parsing takes milliseconds with `-proc:only`. Implemented with performance in head.
+* Intuitive defaults, put `@SharedType` and there you go.
+* Global + class level options. Fine tune your configs.
+* Generics support.
+* (Planed) Constant support.
 
-## Alternatives
+## Similar Projects
 * [bsorrentino/java2typescript](https://github.com/bsorrentino/java2typescript)
 * [vojtechhabarta/typescript-generator](https://github.com/vojtechhabarta/typescript-generator)
 
 ## Documentation
 * [User Guide](doc/Usage.md)
-* [Development Guide](doc/Development.md)
+* [Developer Guide](doc/Development.md)
 
 ## Authors
 Cause Chung (cuzfrog@gmail.com)
diff --git a/doc/Usage.md b/doc/Usage.md
@@ -46,12 +46,7 @@ Setup annotation processing:
 Annotate on a class:
 ```java
 @SharedType
-record User(
-    String name,
-    int age,
-    String email
-) {
-}
+record User(String name, int age, String email) {}
 ```
 
 Execute annotation processing:
diff --git a/processor/src/main/java/org/sharedtype/processor/AnnotationProcessorImpl.java b/processor/src/main/java/org/sharedtype/processor/AnnotationProcessorImpl.java
@@ -66,7 +66,7 @@ public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment
             return ANNOTATION_CONSUMED;
         }
         if (annotations.size() > 1) {
-            throw new SharedTypeInternalError(String.format("Only '%s' is expected.", ANNOTATION_QUALIFIED_NAME));
+            throw new SharedTypeInternalError(String.format("Only annotation %s is expected.", ANNOTATION_QUALIFIED_NAME));
         }
         TypeElement annotation = annotations.iterator().next();
         checkArgument(annotation.getQualifiedName().contentEquals(ANNOTATION_QUALIFIED_NAME), "Wrong anno: %s", annotation);
@@ -88,7 +88,7 @@ void doProcess(Set<? extends Element> elements) {
                     ctx.warning("Type '%s' is ignored or invalid, but annotated with '%s'.", typeElement.getQualifiedName().toString(), ANNOTATION_QUALIFIED_NAME);
                 }
             } else {
-                throw new UnsupportedOperationException("Unsupported element: " + element);
+                throw new SharedTypeInternalError(String.format("Unsupported element: %s of kind %s", element, element.getKind()));
             }
         }
         List<TypeDef> resolvedDefs = resolver.resolve(discoveredDefs);
diff --git a/processor/src/main/java/org/sharedtype/processor/parser/ClassTypeDefParser.java b/processor/src/main/java/org/sharedtype/processor/parser/ClassTypeDefParser.java
@@ -65,7 +65,7 @@ public TypeDef parse(TypeElement typeElement) {
 
     private boolean isValidClassTypeElement(TypeElement typeElement) {
         if (typeElement.getNestingKind() != NestingKind.TOP_LEVEL && !typeElement.getModifiers().contains(Modifier.STATIC)) {
-            ctx.error("Class %s is not static." +
+            ctx.error("Class %s is not static, non-static inner class is not supported." +
                 " Instance class may refer to its enclosing class's generic type without the type declaration on its own," +
                 " which could break the generated code. Later version of SharedType may loosen this limitation.", typeElement);
             return false;
@@ -151,7 +151,7 @@ List<Tuple<Element, String>> resolveComponents(TypeElement typeElement, Config c
                 boolean explicitAccessor = methodElem.getAnnotation(SharedType.Accessor.class) != null;
                 if (!isZeroArgNonstaticMethod(methodElem)) {
                     if (explicitAccessor) {
-                        ctx.warning("Method '%s' annotated with @SharedType.Accessor is not a zero-arg nonstatic method.", methodElem);
+                        ctx.warning("%s.%s annotated with @SharedType.Accessor is not a zero-arg nonstatic method.", typeElement, methodElem);
                     }
                     continue;
                 }
@@ -170,7 +170,8 @@ List<Tuple<Element, String>> resolveComponents(TypeElement typeElement, Config c
             // TODO: CONSTANTS
 
             if (uniqueNamesOfTypes.ignoredType != null) {
-                ctx.error("%s.%s references to explicitly ignored type %s.",typeElement, name, uniqueNamesOfTypes.ignoredType);
+                ctx.error("%s.%s references to explicitly ignored type %s, which is not allowed." +
+                    " Either remove the ignored type, or add @SharedType.Ignore to the field or accessor.",typeElement, name, uniqueNamesOfTypes.ignoredType);
                 return Collections.emptyList();
             }
         }
@@ -217,7 +218,8 @@ boolean contains(String name, TypeMirror componentType) {
                 return false;
             }
             if (!types.isSameType(type, componentType)) {
-                ctx.error("Type %s has components with same name '%s' that have different types '%s' and '%s'", contextType, name, type, componentType);
+                ctx.error("Type %s has conflicting components with same name '%s', because they have different types %s and %s, they cannot be merged.",
+                    contextType, name, type, componentType);
             }
             return true;
         }
diff --git a/processor/src/main/java/org/sharedtype/processor/parser/EnumTypeDefParser.java b/processor/src/main/java/org/sharedtype/processor/parser/EnumTypeDefParser.java
@@ -58,7 +58,7 @@ public TypeDef parse(TypeElement typeElement) {
             .qualifiedName(config.getQualifiedName())
             .simpleName(config.getName())
             .enumValueInfos(
-                enumValueMarker.marked() ? parseEnumConstants(enumConstantElems, enumValueMarker) : useEnumConstantNames(enumConstantElems)
+                enumValueMarker.marked() ? parseEnumConstants(typeElement, enumConstantElems, enumValueMarker) : useEnumConstantNames(enumConstantElems)
             )
             .build();
     }
@@ -71,7 +71,7 @@ private static List<EnumValueInfo> useEnumConstantNames(List<VariableElement> en
         return res;
     }
 
-    private List<EnumValueInfo> parseEnumConstants(List<VariableElement> enumConstants, EnumValueMarker enumValueMarker) {
+    private List<EnumValueInfo> parseEnumConstants(TypeElement enumTypeElement, List<VariableElement> enumConstants, EnumValueMarker enumValueMarker) {
         List<EnumValueInfo> res = new ArrayList<>(enumConstants.size());
         TypeInfo valueTypeInfo = typeInfoParser.parse(enumValueMarker.enumValueVariableElem.asType());
         int ctorArgIdx = enumValueMarker.matchAndGetConstructorArgIdx();
@@ -82,22 +82,24 @@ private List<EnumValueInfo> parseEnumConstants(List<VariableElement> enumConstan
             Tree tree = ctx.getTrees().getTree(enumConstant);
             if (tree instanceof VariableTree) {
                 VariableTree variableTree = (VariableTree) tree;
-                Object value = resolveValue(variableTree, ctorArgIdx);
+                Object value = resolveValue(enumTypeElement, variableTree, ctorArgIdx);
                 if (value != null) {
                     res.add(new EnumValueInfo(valueTypeInfo, value));
                 }
             } else if (tree == null) {
-                ctx.error("Literal value cannot be parsed from enum constant: %s, because source tree from the element is null." +
+                ctx.error("Literal value cannot be parsed from enum constant: %s of enum %s, because source tree from the element is null." +
                     " This could mean at the time of the annotation processing, the source tree was not available." +
-                    " Is this class from a dependency jar/compiled class file? Please refer to the documentation for more information.", enumConstant);
+                    " Is this class from a dependency jar/compiled class file? Please refer to the documentation for more information.",
+                    enumConstant, enumTypeElement);
             } else {
-                throw new SharedTypeInternalError(String.format("Unsupported tree, kind: %s, tree: %s, element: %s", tree.getKind(), tree, enumConstant));
+                throw new SharedTypeInternalError(String.format(
+                    "Unsupported tree during parsing enum %s, kind: %s, tree: %s, element: %s", enumTypeElement, tree.getKind(), tree, enumConstant));
             }
         }
         return res;
     }
 
-    private Object resolveValue(VariableTree tree, int ctorArgIdx) {
+    private Object resolveValue(TypeElement enumTypeElement, VariableTree tree, int ctorArgIdx) {
         ExpressionTree init = tree.getInitializer();
         if (init instanceof NewClassTree) {
             NewClassTree newClassTree = (NewClassTree) init;
@@ -107,16 +109,16 @@ private Object resolveValue(VariableTree tree, int ctorArgIdx) {
                     LiteralTree argLiteralTree = (LiteralTree) argTree;
                     return argLiteralTree.getValue();
                 } else {
-                    ctx.error("Unsupported argument: %s in %s, argIndex: %s. Only literals are supported as enum value."
-                        , argTree, tree, ctorArgIdx);
+                    ctx.error("Unsupported argument in enum type %s: %s in %s, argIndex: %s. Only literals are supported as enum value.",
+                        enumTypeElement, argTree, tree, ctorArgIdx);
                     return null;
                 }
             } catch (IndexOutOfBoundsException e) {
                 throw new SharedTypeInternalError(String.format(
-                    "Initializer has incorrect number of arguments: %s in tree: %s, argIndex: %s", init, tree, ctorArgIdx));
+                    "Initializer in enum %s has incorrect number of arguments: %s in tree: %s, argIndex: %s", enumTypeElement, init, tree, ctorArgIdx));
             }
         }
-        throw new SharedTypeInternalError(String.format("Unsupported initializer: %s in tree: %s", init, tree));
+        throw new SharedTypeInternalError(String.format("Unsupported initializer in enum %s: %s in tree: %s", enumTypeElement, init, tree));
     }
 
     @RequiredArgsConstructor
@@ -142,7 +144,7 @@ void parseConstructor(ExecutableElement constructor) {
 
         void setField(VariableElement enumValueVariableElem) {
             if (this.enumValueVariableElem != null) {
-                ctx.error("Enum '%s' has multiple annotation @%s usage, only one field or constructor parameter is allowed, found on %s and %s",
+                ctx.error("Enum %s has multiple annotation @%s usage, only one field or constructor parameter is allowed, found on %s and %s",
                     config.getQualifiedName(), SharedType.EnumValue.class, this.enumValueVariableElem, enumValueVariableElem);
             } else {
                 this.enumValueVariableElem = enumValueVariableElem;
@@ -166,12 +168,13 @@ int matchAndGetConstructorArgIdx() {
             String lombokSuggestion = "";
             if (constructorArgNames.isEmpty()) {
                 lombokSuggestion = "The discovered constructor has 0 parameter, if Lombok is used to generate the constructor," +
-                    " please ensure annotation processing of Lombok is executed before SharedType.";
+                    " please ensure annotation processing of Lombok is executed before SharedType. Or add explicit constructor." +
+                    " Later version of SharedType may infer constructor parameter position by field position without an explicit constructor.";
             }
 
-            ctx.error("Enum '%s' has @%s annotated on a field, but no constructor parameter can be matched."
+            ctx.error("Enum %s has @%s annotated on a field, but no constructor parameter can be matched."
                     + lombokSuggestion
-                    + " Please refer to the documentation on how to correctly use mark enum value.",
+                    + " May refer to the documentation on how to correctly mark enum value.",
                 config.getQualifiedName(), SharedType.EnumValue.class);
             return -1;
         }
diff --git a/processor/src/main/java/org/sharedtype/processor/parser/type/TypeInfoParserImpl.java b/processor/src/main/java/org/sharedtype/processor/parser/type/TypeInfoParserImpl.java
@@ -46,7 +46,7 @@ public TypeInfo parse(TypeMirror typeMirror) {
         } else if (typeKind == TypeKind.EXECUTABLE) {
             return parse(((ExecutableType) typeMirror).getReturnType());
         }
-        throw new SharedTypeInternalError(String.format("Unsupported field type, element: %s, typeKind: %s", typeMirror, typeKind)); // TODO: context info
+        throw new SharedTypeInternalError(String.format("Unsupported type: %s, typeKind: %s", typeMirror, typeKind));
     }
 
     private TypeInfo parseDeclared(DeclaredType declaredType) {
diff --git a/processor/src/main/java/org/sharedtype/processor/resolver/LoopTypeResolver.java b/processor/src/main/java/org/sharedtype/processor/resolver/LoopTypeResolver.java
@@ -78,7 +78,7 @@ public List<TypeDef> resolve(List<TypeDef> typeDefs) {
                     }
                 }
             } else {
-                throw new SharedTypeInternalError("Unsupported type: " + typeDef.getClass());
+                throw new SharedTypeInternalError("Unsupported TypeDef type: " + typeDef.getClass());
             }
 
             resolveTypeInfo(processingDefStack, processingInfoStack);
@@ -113,11 +113,10 @@ private void resolveTypeInfo(Deque<TypeDef> processingDefStack, Deque<TypeInfo>
                 }
             } else if (typeInfo instanceof TypeVariableInfo) {
                 TypeVariableInfo typeVariableInfo = (TypeVariableInfo) typeInfo;
-                throw new UnsupportedOperationException("Type variable not supported yet: " + typeVariableInfo);
+                throw new SharedTypeInternalError("TypeVariableInfo is not supported yet: " + typeVariableInfo);
             } else {
-                throw new SharedTypeInternalError(
-                    String.format("Only ConcreteTypeInfo needs to be resolved, but got typeInfo: %s with %s", typeInfo, typeInfo.getClass())
-                );
+                throw new SharedTypeInternalError(String.format(
+                    "Only ConcreteTypeInfo needs to be resolved, but got: %s of %s", typeInfo, typeInfo.getClass()));
             }
         }
     }

Original file line number	Diff line number	Diff line change
`@@ -66,7 +66,7 @@ public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment`
`66`	`66`	`return ANNOTATION_CONSUMED;`
`67`	`67`	`}`
`68`	`68`	`if (annotations.size() > 1) {`
`69`		`- throw new SharedTypeInternalError(String.format("Only '%s' is expected.", ANNOTATION_QUALIFIED_NAME));`
	`69`	`+ throw new SharedTypeInternalError(String.format("Only annotation %s is expected.", ANNOTATION_QUALIFIED_NAME));`
`70`	`70`	`}`
`71`	`71`	`TypeElement annotation = annotations.iterator().next();`
`72`	`72`	`checkArgument(annotation.getQualifiedName().contentEquals(ANNOTATION_QUALIFIED_NAME), "Wrong anno: %s", annotation);`
`@@ -88,7 +88,7 @@ void doProcess(Set<? extends Element> elements) {`
`88`	`88`	`ctx.warning("Type '%s' is ignored or invalid, but annotated with '%s'.", typeElement.getQualifiedName().toString(), ANNOTATION_QUALIFIED_NAME);`
`89`	`89`	`}`
`90`	`90`	`} else {`
`91`		`- throw new UnsupportedOperationException("Unsupported element: " + element);`
	`91`	`+ throw new SharedTypeInternalError(String.format("Unsupported element: %s of kind %s", element, element.getKind()));`
`92`	`92`	`}`
`93`	`93`	`}`
`94`	`94`	`List<TypeDef> resolvedDefs = resolver.resolve(discoveredDefs);`
Original file line number	Diff line number	Diff line change
`@@ -65,7 +65,7 @@ public TypeDef parse(TypeElement typeElement) {`
`65`	`65`
`66`	`66`	`private boolean isValidClassTypeElement(TypeElement typeElement) {`
`67`	`67`	`if (typeElement.getNestingKind() != NestingKind.TOP_LEVEL && !typeElement.getModifiers().contains(Modifier.STATIC)) {`
`68`		`- ctx.error("Class %s is not static." +`
	`68`	`+ ctx.error("Class %s is not static, non-static inner class is not supported." +`
`69`	`69`	`" Instance class may refer to its enclosing class's generic type without the type declaration on its own," +`
`70`	`70`	`" which could break the generated code. Later version of SharedType may loosen this limitation.", typeElement);`
`71`	`71`	`return false;`
`@@ -151,7 +151,7 @@ List<Tuple<Element, String>> resolveComponents(TypeElement typeElement, Config c`
`151`	`151`	`boolean explicitAccessor = methodElem.getAnnotation(SharedType.Accessor.class) != null;`
`152`	`152`	`if (!isZeroArgNonstaticMethod(methodElem)) {`
`153`	`153`	`if (explicitAccessor) {`
`154`		`- ctx.warning("Method '%s' annotated with @SharedType.Accessor is not a zero-arg nonstatic method.", methodElem);`
	`154`	`+ ctx.warning("%s.%s annotated with @SharedType.Accessor is not a zero-arg nonstatic method.", typeElement, methodElem);`
`155`	`155`	`}`
`156`	`156`	`continue;`
`157`	`157`	`}`
`@@ -170,7 +170,8 @@ List<Tuple<Element, String>> resolveComponents(TypeElement typeElement, Config c`
`170`	`170`	`// TODO: CONSTANTS`
`171`	`171`
`172`	`172`	`if (uniqueNamesOfTypes.ignoredType != null) {`
`173`		`- ctx.error("%s.%s references to explicitly ignored type %s.",typeElement, name, uniqueNamesOfTypes.ignoredType);`
	`173`	`+ ctx.error("%s.%s references to explicitly ignored type %s, which is not allowed." +`
	`174`	`+ " Either remove the ignored type, or add @SharedType.Ignore to the field or accessor.",typeElement, name, uniqueNamesOfTypes.ignoredType);`
`174`	`175`	`return Collections.emptyList();`
`175`	`176`	`}`
`176`	`177`	`}`
`@@ -217,7 +218,8 @@ boolean contains(String name, TypeMirror componentType) {`
`217`	`218`	`return false;`
`218`	`219`	`}`
`219`	`220`	`if (!types.isSameType(type, componentType)) {`
`220`		`- ctx.error("Type %s has components with same name '%s' that have different types '%s' and '%s'", contextType, name, type, componentType);`
	`221`	`+ ctx.error("Type %s has conflicting components with same name '%s', because they have different types %s and %s, they cannot be merged.",`
	`222`	`+ contextType, name, type, componentType);`
`221`	`223`	`}`
`222`	`224`	`return true;`
`223`	`225`	`}`
Original file line number	Diff line number	Diff line change
`@@ -46,7 +46,7 @@ public TypeInfo parse(TypeMirror typeMirror) {`
`46`	`46`	`} else if (typeKind == TypeKind.EXECUTABLE) {`
`47`	`47`	`return parse(((ExecutableType) typeMirror).getReturnType());`
`48`	`48`	`}`
`49`		`- throw new SharedTypeInternalError(String.format("Unsupported field type, element: %s, typeKind: %s", typeMirror, typeKind)); // TODO: context info`
	`49`	`+ throw new SharedTypeInternalError(String.format("Unsupported type: %s, typeKind: %s", typeMirror, typeKind));`
`50`	`50`	`}`
`51`	`51`
`52`	`52`	`private TypeInfo parseDeclared(DeclaredType declaredType) {`
Original file line number	Diff line number	Diff line change
`@@ -78,7 +78,7 @@ public List<TypeDef> resolve(List<TypeDef> typeDefs) {`
`78`	`78`	`}`
`79`	`79`	`}`
`80`	`80`	`} else {`
`81`		`- throw new SharedTypeInternalError("Unsupported type: " + typeDef.getClass());`
	`81`	`+ throw new SharedTypeInternalError("Unsupported TypeDef type: " + typeDef.getClass());`
`82`	`82`	`}`
`83`	`83`
`84`	`84`	`resolveTypeInfo(processingDefStack, processingInfoStack);`
`@@ -113,11 +113,10 @@ private void resolveTypeInfo(Deque<TypeDef> processingDefStack, Deque<TypeInfo>`
`113`	`113`	`}`
`114`	`114`	`} else if (typeInfo instanceof TypeVariableInfo) {`
`115`	`115`	`TypeVariableInfo typeVariableInfo = (TypeVariableInfo) typeInfo;`
`116`		`- throw new UnsupportedOperationException("Type variable not supported yet: " + typeVariableInfo);`
	`116`	`+ throw new SharedTypeInternalError("TypeVariableInfo is not supported yet: " + typeVariableInfo);`
`117`	`117`	`} else {`
`118`		`- throw new SharedTypeInternalError(`
`119`		`- String.format("Only ConcreteTypeInfo needs to be resolved, but got typeInfo: %s with %s", typeInfo, typeInfo.getClass())`
`120`		`- );`
	`118`	`+ throw new SharedTypeInternalError(String.format(`
	`119`	`+ "Only ConcreteTypeInfo needs to be resolved, but got: %s of %s", typeInfo, typeInfo.getClass()));`
`121`	`120`	`}`
`122`	`121`	`}`
`123`	`122`	`}`