feat (core): Graphviz DocGen, used on https://docs.enola.dev/concepts…

…/graph/ (re. enola-dev#502)

ToDo.yaml

@@ -74,6 +74,11 @@ items:
       items:
         - ? Write `todo.esch.yaml` & `todo-context.jsonld` in `models/enola.dev/todo/`
 
+  - Visualize Graphs in 3D:
+      links:
+        - https://graphviz.org/docs/outputs/pov/
+        - https://graphviz.org/docs/outputs/vrml/
+
   - Validation:
       depends: [*metaJavaCodegen]
 

docs/concepts/graph.md

@@ -0,0 +1,25 @@
+<!--
+    SPDX-License-Identifier: Apache-2.0
+
+    Copyright 2024 The Enola <https://enola.dev> Authors
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+-->
+
+# Graph
+
+![Models](../models/graphviz.gv.svg)
+
+Best viewed with right-click to _Open image in new tab,_ and scrolling.
+
+Interactive graph [coming up](https://github.com/enola-dev/enola/issues/502).

java/dev/enola/common/context/Context.java

@@ -65,7 +65,7 @@ public <K extends Enum<K> & Key<T>, T> Context push(K key, T value) {
         return _push(key, value);
     }
 
-    public <T, K extends Enum<K>> Context push(Class<T> key, T value) {
+    public <T> Context push(Class<T> key, T value) {
         _push(key, value); // NOT .getName()
         return this;
     }

java/dev/enola/common/context/TLC.java

@@ -53,7 +53,7 @@ public static Context open() {
 
     /** See {@link dev.enola.common.context.Context#get(Class)} . */
     public static <K extends Enum<K> & Context.Key<T>, T> @Nullable T get(K key) {
-        return context().get(key);
+        return context(key).get(key);
     }
 
     public static <K extends Enum<K> & Context.Key<T>, T> Optional<T> optional(K key) {
@@ -64,7 +64,7 @@ public static <K extends Enum<K> & Context.Key<T>, T> Optional<T> optional(K key
 
     /** See {@link dev.enola.common.context.Context#get(java.lang.Class). */
     public static <T> @Nullable T get(Class<T> klass) {
-        return context().get(klass);
+        return context(klass).get(klass);
     }
 
     public static <T> Optional<T> optional(Class<T> klass) {
@@ -73,10 +73,11 @@ public static <T> Optional<T> optional(Class<T> klass) {
         return tlc.optional(klass);
     }
 
-    private static Context context() {
+    private static Context context(Object debug) {
         var tlc = threadLocalContext.get();
         if (tlc == null) {
-            throw new IllegalStateException("Missing TLC.open() in call chain!");
+            throw new IllegalStateException(
+                    "Missing TLC.open() in call chain, can't get: " + debug);
         }
         return tlc;
     }

java/dev/enola/thing/gen/BUILD

@@ -21,7 +21,10 @@ java_library(
     name = "gen",
     srcs = glob(
         ["**/*.java"],
-        exclude = ["**/*Test.java"],
+        exclude = [
+            "**/*Test.java",
+            "**/Test*.java",
+        ],
     ),
     plugins = ["//tools/bazel/java_plugin:autoservice"],
     visibility = ["//:__subpackages__"],
@@ -33,6 +36,7 @@ java_library(
         "//java/dev/enola/common/io",
         "//java/dev/enola/common/tree",
         "//java/dev/enola/data",
+        "//java/dev/enola/datatype",
         "//java/dev/enola/rdf",
         "//java/dev/enola/thing:thing_java",
         # TODO Remove Proto dependency, switch to pure Java API
@@ -48,9 +52,16 @@ java_library(
 
 junit_tests(
     name = "tests",
-    srcs = glob(["**/*Test.java"]),
+    srcs = glob([
+        "**/*Test.java",
+    ]),
+    srcs_utils = glob(
+        ["**/*Test*.java"],
+        exclude = ["**/*Test.java"],
+    ),
     deps = [
         ":gen",
+        "//java/dev/enola/common/context",
         "//java/dev/enola/common/io",
         "//java/dev/enola/datatype",
         "//java/dev/enola/model",

java/dev/enola/thing/gen/graphviz/GraphvizGenerator.java

@@ -17,11 +17,15 @@
  */
 package dev.enola.thing.gen.graphviz;
 
+import com.google.common.escape.Escaper;
+import com.google.common.html.HtmlEscapers;
+
 import dev.enola.common.context.TLC;
 import dev.enola.common.convert.ConversionException;
 import dev.enola.common.convert.ConverterIntoAppendable;
 import dev.enola.common.io.metadata.Metadata;
 import dev.enola.common.io.metadata.MetadataProvider;
+import dev.enola.common.io.resource.WritableResource;
 import dev.enola.thing.PredicatesObjects;
 import dev.enola.thing.Thing;
 import dev.enola.thing.repo.StackedThingProvider;
@@ -59,6 +63,13 @@ public GraphvizGenerator(MetadataProvider metadataProvider) {
         this.metadataProvider = metadataProvider;
     }
 
+    public void convertIntoOrThrow(Iterable<Thing> things, WritableResource into)
+            throws ConversionException, IOException {
+        try (var out = into.charSink().openBufferedStream()) {
+            convertIntoOrThrow(things, out);
+        }
+    }
+
     @Override
     public boolean convertInto(Iterable<Thing> from, Appendable out)
             throws ConversionException, IOException {
@@ -104,18 +115,25 @@ private void printNonLinkPropertiesTable(
         out.append("<TABLE BORDER=\"0\" CELLBORDER=\"1\" CELLSPACING=\"0\">\n");
         if (thingLabel != null) {
             out.append("    <TR><TD COLSPAN=\"2\">");
-            out.append(thingLabel);
+            out.append(html(thingLabel));
             out.append("</TD></TR>\n");
         }
         for (var p : thing.predicateIRIs()) {
             if (thing.isLink(p)) continue;
             var pLabel = label(metadataProvider.get(p));
             out.append("    <TR><TD ALIGN=\"left\">");
-            out.append(pLabel);
+            out.append(html(pLabel));
             out.append("</TD><TD>");
-            out.append(thing.getString(p));
+            var value = thing.getString(p);
+            if (value != null) out.append(html(value));
             out.append("</TD></TR>\n");
         }
         out.append("  </TABLE>");
     }
+
+    private static final Escaper htmlEscaper = HtmlEscapers.htmlEscaper();
+
+    private String html(String text) {
+        return htmlEscaper.escape(text);
+    }
 }

java/dev/enola/thing/gen/graphviz/GraphvizResourceConverter.java

@@ -50,9 +50,7 @@ public boolean convertIntoThrows(ReadableResource from, WritableResource into)
         }
 
         var things = store.build().list();
-        try (var out = into.charSink().openBufferedStream()) {
-            graphvizGenerator.convertIntoOrThrow(things, out);
-            return true;
-        }
+        graphvizGenerator.convertIntoOrThrow(things, into);
+        return true;
     }
 }

java/dev/enola/thing/gen/markdown/MarkdownSiteGenerator.java

@@ -18,14 +18,19 @@
 package dev.enola.thing.gen.markdown;
 
 import com.google.common.collect.ImmutableSortedSet;
+import com.google.common.collect.Iterables;
 
+import dev.enola.common.context.TLC;
 import dev.enola.common.function.CheckedPredicate;
 import dev.enola.common.io.MoreFileSystems;
 import dev.enola.common.io.metadata.Metadata;
 import dev.enola.common.io.metadata.MetadataProvider;
 import dev.enola.common.io.resource.ResourceProvider;
 import dev.enola.data.ProviderFromIRI;
+import dev.enola.datatype.DatatypeRepository;
 import dev.enola.thing.gen.Relativizer;
+import dev.enola.thing.gen.graphviz.GraphvizGenerator;
+import dev.enola.thing.message.ThingAdapter;
 import dev.enola.thing.proto.Thing;
 import dev.enola.thing.template.TemplateService;
 import dev.enola.thing.template.Templates;
@@ -35,6 +40,7 @@
 
 import java.io.IOException;
 import java.net.URI;
+import java.util.ArrayList;
 
 /** Generates a "site" of Markdown files, given some Things. */
 public class MarkdownSiteGenerator {
@@ -45,6 +51,7 @@ public class MarkdownSiteGenerator {
     private final MarkdownThingGenerator mtg;
     private final MetadataProvider metadataProvider;
     private final Templates.Format format;
+    private final GraphvizGenerator graphvizGenerator;
 
     public MarkdownSiteGenerator(
             URI base,
@@ -66,6 +73,7 @@ public MarkdownSiteGenerator(
         this.metadataProvider = metadataProvider;
         this.mtg = new MarkdownThingGenerator(format, metadataProvider);
         this.rp = rp;
+        this.graphvizGenerator = new GraphvizGenerator(metadataProvider);
     }
 
     public void generate(
@@ -77,6 +85,8 @@ public void generate(
             boolean footer)
             throws IOException {
 
+        generateGraphviz(things);
+
         var metas = ImmutableSortedSet.orderedBy(Metadata.IRI_Comparator);
 
         // TODO Do this multi-threaded, in parallel... (but BEWARE ImmutableMap not thread safe!)
@@ -113,4 +123,17 @@ public void generate(
             }
         }
     }
+
+    private void generateGraphviz(Iterable<Thing> protoThings) throws IOException {
+        var graphvizOutputIRI = base.resolve("graphviz.gv");
+        var graphVizOutputResource = rp.getWritableResource(graphvizOutputIRI);
+
+        var dtr = TLC.get(DatatypeRepository.class);
+        var javaThings = new ArrayList<dev.enola.thing.Thing>(Iterables.size(protoThings));
+        for (var protoThing : protoThings) {
+            javaThings.add(new ThingAdapter(protoThing, dtr));
+        }
+
+        graphvizGenerator.convertIntoOrThrow(javaThings, graphVizOutputResource);
+    }
 }

java/dev/enola/thing/gen/markdown/MarkdownSiteGeneratorTest.java

@@ -21,6 +21,7 @@
 
 import static dev.enola.thing.template.Templates.Format.Mustache;
 
+import com.google.common.collect.ImmutableMap;
 import com.google.common.collect.ImmutableSet;
 
 import dev.enola.common.io.iri.namespace.NamespaceConverter;
@@ -47,7 +48,9 @@
 import dev.enola.thing.template.TemplateService;
 import dev.enola.thing.template.TemplateThingRepository;
 
+import org.junit.Rule;
 import org.junit.Test;
+import org.junit.rules.TestRule;
 
 import java.io.IOException;
 import java.net.URI;
@@ -59,6 +62,10 @@
 
 public class MarkdownSiteGeneratorTest {
 
+    @Rule
+    public TestRule tlcRule =
+            new TestTLCRule(ImmutableMap.of(DatatypeRepository.class, Datatypes.DTR));
+
     ThingProvider NO_THING_PROVIDER = iri -> null;
 
     DatatypeRepository dtr = Datatypes.DTR;

java/dev/enola/thing/gen/markdown/TestTLCRule.java

@@ -0,0 +1,59 @@
+/*
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Copyright 2024 The Enola <https://enola.dev> Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package dev.enola.thing.gen.markdown;
+
+import com.google.common.collect.ImmutableMap;
+
+import dev.enola.common.context.TLC;
+
+import org.junit.rules.TestRule;
+import org.junit.runner.Description;
+import org.junit.runners.model.Statement;
+
+public class TestTLCRule implements TestRule {
+
+    // TODO Move this class into a new context.testlib package
+
+    private final ImmutableMap<Class<?>, ?> pushes;
+
+    public <K> TestTLCRule(ImmutableMap<Class<?>, ?> pushes) {
+        this.pushes = pushes;
+    }
+
+    @Override
+    public Statement apply(Statement base, Description description) {
+        return statement(base);
+    }
+
+    @SuppressWarnings("unchecked")
+    private <T> Statement statement(Statement base) {
+        return new Statement() {
+            @Override
+            public void evaluate() throws Throwable {
+                try (var ctx = TLC.open()) {
+                    for (var push : pushes.entrySet()) {
+                        Class<T> clazz = (Class<T>) push.getKey();
+                        T instance = (T) push.getValue();
+                        ctx.push(clazz, instance);
+                    }
+                    base.evaluate();
+                }
+            }
+        };
+    }
+}

mkdocs.yaml

@@ -53,7 +53,9 @@ nav:
       - Canonicalize: use/canonicalize/index.md
       - ExecMD: use/execmd/index.md
       - Info: use/info/index.md
-  - Models: models/index.md
+  - Models:
+      - Index: models/index.md
+      - Graph: concepts/graph.md
   - Concepts:
       - Core: concepts/core.md
       - Architecture Diagrams: concepts/core-arch.md

models/build.bash

@@ -38,6 +38,7 @@ mv .built/linkml docs/models/
 # TODO Support --load *.rdf application/rdf+xml : That's quite simple, really; just requires piping through RIO.
 # TODO Support --load *.owl : Could map it into enola.meta.Schema? But... what's the priority of this, really?
 ./enola -vvv docgen --load="docs/models/**" --output=docs/models/
+dot -Tsvg -O docs/models/graphviz.gv
 
 # TODO Support GLOBs in rosetta like in docgen? (Low priority, because DocGen will gen. embedded JSON-LD anyway.)
 ./enola -v rosetta --in=models/enola.dev.ttl --out=docs/models/enola.dev.jsonld

test/graphviz.expected.gv

@@ -8,7 +8,7 @@ digraph {
 
   "https://example.org/greeting3" [shape=plain label=<<TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0">
     <TR><TD COLSPAN="2">👋ex:greeting3</TD></TR>
-    <TR><TD ALIGN="left">ex:message</TD><TD>hello, world</TD></TR>
+    <TR><TD ALIGN="left">ex:message</TD><TD>hello, world &gt; 42</TD></TR>
   </TABLE>>]
   "https://example.org/greeting3" -> "https://example.org/Salutation" [label="rdf:type"]
   "https://example.org/greeting3" -> "https://example.org/world" [label="ex:object"]

test/graphviz.ttl

@@ -10,7 +10,7 @@
   enola:emoji "👋".
 
 :greeting3 a :Salutation;
-  :message "hello, world";
+  :message "hello, world > 42"; # The '>' needs escaping in GV HTML-like Labels
   :object :world.
 
 :world