[Renzu processor] UML generation for Typeclass + Instances info graph #812

JorgeCastilloPrz · 2018-04-22T10:07:09Z

Renzu is just the codename for now, it stands for "lens" in Japanese. Not directly related to FP prisms / lenses but also to the concept of looking to something through a lens to discover a new perspective over it. That's kind of what this diagrams are. Name is open for discussion.

This processor generates UML text recognized by nomnoml frontend lib to render UML diagrams.

Added processor tests using compile-testing.
Added relations between typeclasses and instances. Now it generates UML with a form similar to the following (but much more extense, ofc):

#font: Menlo
#fontSize: 15
#arrowSize: 1
#bendSize: 0.3
#lineWidth: 2
#padding: 8
#zoom: 1
#fill: #64B5F6
#.typeclass: fill=#64B5F6 visual=database bold
#.instances: fill=#B9F6CA visual=class italic bold dashed
[<typeclass>Semigroup]<-[<instances>Semigroup Instances|OptionMonoidInstance|OptionSemigroupInstance]
[<typeclass>Semigroup]<-[<typeclass>Monoid]
[<typeclass>Monoid]<-[<instances>Monoid Instances|OptionMonoidInstance]

Which renders to:

I've decided to group instances for the same typeclass in a single box for the time being given the way nomnoml aligns childs horizontally on 1 -> N relations (it would grow sooo much horizontally).

To generate test stubs if you get problems on those:
./gradlew clean :arrow-annotations-processor-test-models:assemble :arrow-annotations-processor:test

codecov · 2018-04-22T10:24:45Z

Codecov Report

Merging #812 into master will increase coverage by 0.78%.
The diff coverage is 67.79%.

@@             Coverage Diff              @@
##             master     #812      +/-   ##
============================================
+ Coverage      43.5%   44.29%   +0.78%     
- Complexity      584      617      +33     
============================================
  Files           284      289       +5     
  Lines          7259     7376     +117     
  Branches        804      828      +24     
============================================
+ Hits           3158     3267     +109     
+ Misses         3819     3810       -9     
- Partials        282      299      +17

Impacted Files	Coverage Δ	Complexity Δ
...ava/arrow/ap/objects/renzu/OptionMonoidInstance.kt	`0% <0%> (ø)`	`0 <0> (?)`
...src/main/java/arrow/instances/AnnotatedInstance.kt	`80% <0%> (+80%)`	`4 <0> (+4)`	⬆️
.../arrow/ap/objects/renzu/OptionSemigroupInstance.kt	`0% <0%> (ø)`	`0 <0> (?)`
...src/main/java/arrow/common/utils/ProcessorUtils.kt	`42.04% <20%> (+23.97%)`	`0 <0> (ø)`	⬇️
...rocessor/src/main/java/arrow/renzu/ModuleStyles.kt	`60% <60%> (ø)`	`0 <0> (?)`
...cessor/src/main/java/arrow/renzu/RenzuGenerator.kt	`74.02% <74.02%> (ø)`	`17 <17> (?)`
...cessor/src/main/java/arrow/renzu/RenzuProcessor.kt	`79.16% <79.16%> (ø)`	`12 <12> (?)`
... and 5 more

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 3237249...f51048b. Read the comment docs.

JorgeCastilloPrz · 2018-04-24T08:57:53Z

Ok, this is starting to look better. Processor tests are now passing, and I've added relations between typeclasses. Now it generates UML with the form:

#font: Menlo
#fontSize: 15
#arrowSize: 1
#bendSize: 0.3
#lineWidth: 2
#padding: 8
#zoom: 1
#fill: #64B5F6
#.typeclass: fill=#64B5F6 visual=database bold
#.instances: fill=#B9F6CA visual=class italic bold dashed
[<typeclass>Semigroup]<-[<instances>Semigroup Instances|OptionMonoidInstance|OptionSemigroupInstance]
[<typeclass>Semigroup]<-[<typeclass>Monoid]
[<typeclass>Monoid]<-[<instances>Monoid Instances|OptionMonoidInstance]

Which renders to:

I've decided to group instances for the same typeclass in a single box for the time being given the way nomnoml aligns childs horizontally on 1 -> N relations (it would grow sooo much horizontally).

I keep iterating on it. Now I'll try to colorize them differently depending on the package they belong to, like here

…e to avoid collisions

JorgeCastilloPrz · 2018-04-26T11:52:38Z

Can you take a look @raulraja ? I'd need a green here in order to let you test it. It requires the frontend side to be deployed also, which is included here.

No worries, this does not break any compilation / CI or anything, so should be safe to merge. Take a rapid look if you rather, though.

When this gets merged I have a plan to make not merged PRs provide a link on the CI console so you can visualize their current graph state.

raulraja · 2018-04-26T15:12:08Z

...ow-annotations-processor/models/src/main/java/arrow/ap/objects/renzu/OptionMonoidInstance.kt

+import arrow.typeclasses.Monoid
+
+@instance(Option::class)
+interface OptionMonoidInstance<A> : OptionSemigroupInstance<A>, Monoid<Option<A>> {


are these for testing purposes?

Yep, these are just clones of real instances inside the processor models module for testing

raulraja · 2018-04-26T15:14:10Z

modules/core/arrow-annotations-processor/src/main/java/arrow/renzu/RenzuGenerator.kt

+            val className = i.removeBackticks().substringBefore("<")
+            val typeClassElement = processor.elementUtils.getTypeElement(className)
+            val parentInterface = processor.getClassOrPackageDataWrapper(typeClassElement) as ClassOrPackageDataWrapper.Class
+            if (i.removeBackticks().contains("typeclass")) {


Can this fail if the type class extends an interface in the same package that is not a type class?

The supertypes are extracted from the typetable and here we're just adding them to the typeclass collection if they are actually typeclasses, so this shouldn't fail IMO

raulraja · 2018-04-26T15:19:10Z

modules/core/arrow-annotations-processor/src/main/java/arrow/renzu/RenzuGenerator.kt

+
+  private fun normalizeTypeclassTree(instances: List<Instance>)
+    : MutableMap<TypeClass, Tuple2<Instances, Set<ParentTypeClass>>> =
+    instances.fold(mutableMapOf()) { acc, instance ->


Can this be implemented in terms of an immutable map instead?

raulraja · 2018-04-26T15:22:23Z

modules/core/arrow-annotations-processor/src/main/java/arrow/renzu/RenzuGenerator.kt

+    val file = File(generatedDir, "arrow-infographic.txt")
+    if (!file.exists()) {
+      val globalStyles =
+        listOf("#font: Menlo") +


This can be probably expressed as a string template:

val globalStyles = """ |#font: Menlo |... """.trimMarging()

raulraja · 2018-04-26T15:28:36Z

modules/core/arrow-annotations-processor/src/main/java/arrow/renzu/RenzuGenerator.kt

+   */
+  private fun genDiagramRelations(typeclassTree: MutableMap<TypeClass, Tuple2<Instances, Set<ParentTypeClass>>>)
+    : List<String> {
+    val relations = mutableListOf<String>()


We can encode this entire method without mutability just flatMapping over typeclassTree

raulraja · 2018-04-26T15:34:18Z

AwesomeSauce!

JorgeCastilloPrz · 2018-04-26T18:12:13Z

All the stuff has been fixed @raulraja , I'll merge whenever CI has the will to let me.

…arrow-kt#812) * Added Renzu annotation processor to generate UML renderable by the docs site. * Added tests to ensure integrity. * Added isolated infograph UML version for tests. * Added new section for the website (/graph) to browse the typeclasses and instances graph.

JorgeCastilloPrz added the work in progress label Apr 22, 2018

JorgeCastilloPrz self-assigned this Apr 22, 2018

JorgeCastilloPrz force-pushed the renzu branch from 89e26b5 to 8604971 Compare April 24, 2018 09:40

Jorge Castillo and others added 25 commits April 26, 2018 13:50

first version of Renzu processor for UML generation

69f8d81

remove renzu annotation not required anymore

4384184

add early not passing tests

482fb6b

Fix annotation processing

81c2aa0

keep global list of annotated elements over different processing rounds

f4b725e

fix npe on generator

8c309ef

remove wrong iteration when trying to generate UML

1b62c8e

fix wrong file location generation

a78d1f3

write out tc simple names instead of fullnames

6308112

extract TypeClass meta model to avoid duplication

978f475

fix instance names

eaa21db

replace List by Set for instances to avoid duplication

c82673b

fix instances problem causing them to group wrongly

16153a7

add relations between typeclasses and fix tests once forever

1bf2f48

prepare to render different colors per module

0164510

add logs reporting successful UML generation and file path

19f96d9

fix detekt complaints

8963756

set graph font size to 10

62f1aac

fix tests

8cd7c54

write files to root dir infographic/ folder

36412ab

fix new line chars

4595b93

delete renzu infographic after running tests, not before

f1d057a

clean infographic file whenever clean command is run on any module

def137c

add website section

ae314ba

up to date

e44c217

JorgeCastilloPrz added 5 commits April 26, 2018 13:50

fix graph section linking

f7b1ed4

test

3a24eb9

fix problem causing graph to also generate on inner modules

ade3bca

remove duplicated relations and isolate tests to work over a diff fil…

1a3ce00

…e to avoid collisions

update frontend to read generated infographic

16c0e91

JorgeCastilloPrz force-pushed the renzu branch from 3aa491e to 16c0e91 Compare April 26, 2018 11:50

JorgeCastilloPrz requested a review from raulraja April 26, 2018 11:53

JorgeCastilloPrz removed the work in progress label Apr 26, 2018

update graph

199bb9a

raulraja approved these changes Apr 26, 2018

View reviewed changes

JorgeCastilloPrz added 4 commits April 26, 2018 18:23

use immutable map to normalize the typeclass tree

28271bb

use string template for global UML styles

cacb6cf

refactor generation method to remove mutability

49c8489

up to date

f51048b

JorgeCastilloPrz merged commit 40baca8 into master Apr 26, 2018

JorgeCastilloPrz deleted the renzu branch April 26, 2018 18:33

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Renzu processor] UML generation for Typeclass + Instances info graph #812

[Renzu processor] UML generation for Typeclass + Instances info graph #812

JorgeCastilloPrz commented Apr 22, 2018 •

edited

Loading

codecov bot commented Apr 22, 2018 •

edited

Loading

JorgeCastilloPrz commented Apr 24, 2018 •

edited

Loading

JorgeCastilloPrz commented Apr 26, 2018

raulraja Apr 26, 2018

JorgeCastilloPrz Apr 26, 2018

raulraja Apr 26, 2018

JorgeCastilloPrz Apr 26, 2018 •

edited

Loading

raulraja Apr 26, 2018

raulraja Apr 26, 2018

raulraja Apr 26, 2018

raulraja commented Apr 26, 2018

JorgeCastilloPrz commented Apr 26, 2018

[Renzu processor] UML generation for Typeclass + Instances info graph #812

[Renzu processor] UML generation for Typeclass + Instances info graph #812

Conversation

JorgeCastilloPrz commented Apr 22, 2018 • edited Loading

codecov bot commented Apr 22, 2018 • edited Loading

Codecov Report

JorgeCastilloPrz commented Apr 24, 2018 • edited Loading

JorgeCastilloPrz commented Apr 26, 2018

raulraja Apr 26, 2018

Choose a reason for hiding this comment

JorgeCastilloPrz Apr 26, 2018

Choose a reason for hiding this comment

raulraja Apr 26, 2018

Choose a reason for hiding this comment

JorgeCastilloPrz Apr 26, 2018 • edited Loading

Choose a reason for hiding this comment

raulraja Apr 26, 2018

Choose a reason for hiding this comment

raulraja Apr 26, 2018

Choose a reason for hiding this comment

raulraja Apr 26, 2018

Choose a reason for hiding this comment

raulraja commented Apr 26, 2018

JorgeCastilloPrz commented Apr 26, 2018

JorgeCastilloPrz commented Apr 22, 2018 •

edited

Loading

codecov bot commented Apr 22, 2018 •

edited

Loading

JorgeCastilloPrz commented Apr 24, 2018 •

edited

Loading

JorgeCastilloPrz Apr 26, 2018 •

edited

Loading