WIP Next Phase...

This includes only indirectly related work, such as:

* Add check-jsonschema pre-commit

Author: vorburger

.bazelrc

@@ -4,6 +4,7 @@
 common --enable_bzlmod
 common --extra_toolchains=@local_jdk//:all
 
+# Java version must match .devcontainer/devcontainer.json
 # https://bazel.build/docs/bazel-and-java#java-versions
 build --java_language_version=21
 build --tool_java_language_version=21

.devcontainer/devcontainer.json

@@ -22,8 +22,13 @@
 
   // Features to add to the dev container. More info: https://containers.dev/features.
   "features": {
+    // Java version must match .bazelrc
     "ghcr.io/devcontainers/features/java:1": {
       "version": "21"
+    },
+    // protoc is used by tools/protoc/protoc.bash
+    "ghcr.io/devcontainers-contrib/features/protoc-asdf:1": {
+      "version": "3.6.1"
     }
   },
 

.editorconfig

@@ -47,14 +47,17 @@ max_line_length = unset
 max_line_length = unset
 indent_size = 2
 tab_width = 2
+max_line_length = unset
 
 [*.jsonc]
 indent_size = 2
 tab_width = 2
+max_line_length = unset
 
 [*.json5]
 indent_size = 2
 tab_width = 2
+max_line_length = unset
 
 [*.toml]
 indent_size = 2

.github/dependabot.yml

@@ -14,3 +14,10 @@ updates:
       day: monday
       time: "04:00"
     open-pull-requests-limit: 99
+  - package-ecosystem: "devcontainers"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+      day: monday
+      time: "04:00"
+    open-pull-requests-limit: 99

.pre-commit-config.yaml

@@ -152,13 +152,44 @@ repos:
     hooks:
       - id: csslint
 
-  # https://editorconfig.org check should run AFTER all of the formatters (above)
-  - repo: https://github.com/editorconfig-checker/editorconfig-checker.python
-    rev: 2.7.3
+  # https://yamllint.readthedocs.io/en/stable/integration.html#integration-with-pre-commit
+  - repo: https://github.com/adrienverge/yamllint.git
+    rev: v1.33.0
     hooks:
-      - id: editorconfig-checker
+      - id: yamllint
+        # https://yamllint.readthedocs.io/en/stable/configuration.html#errors-and-warnings
+        args: [--strict]
 
   - repo: https://github.com/shellcheck-py/shellcheck-py
     rev: v0.9.0.6
     hooks:
       - id: shellcheck
+
+  - repo: https://github.com/python-jsonschema/check-jsonschema
+    rev: 0.28.0
+    hooks:
+      - id: check-github-actions
+        args: ["--verbose"]
+      - id: check-github-workflows
+        args: ["--verbose"]
+      - id: check-dependabot
+        args: ["--verbose"]
+      - id: check-renovate
+        args: ["--verbose"]
+      - id: check-metaschema
+        files: \.schema\.json$
+        args: ["--verbose"]
+      # TODO Change once https://github.com/python-jsonschema/check-jsonschema/issues/340 is implemented
+      - id: check-jsonschema
+        # files: .+/models/.+\.(yaml|json)$
+        files: \.types\.yaml$
+        args: ["--verbose", "--schemafile", "docs/models/enola/schemas/Types.schema.json"]
+      - id: check-jsonschema
+        files: \.type\.yaml$
+        args: ["--verbose", "--schemafile", "docs/models/enola/schemas/Type.schema.json"]
+
+  # https://editorconfig.org check should run AFTER all of the formatters (above)
+  - repo: https://github.com/editorconfig-checker/editorconfig-checker.python
+    rev: 2.7.3
+    hooks:
+      - id: editorconfig-checker

.vscode/extensions.json

@@ -16,6 +16,10 @@
     "zignd.html-css-class-completion",
     "timonwong.shellcheck"
   ],
-  // https://github.com/kshetline/ligatures-limited/issues/39
-  "unwantedRecommendations": ["kshetline.ligatures-limited"]
+  "unwantedRecommendations": [
+    // https://github.com/kshetline/ligatures-limited/issues/39
+    "kshetline.ligatures-limited",
+    "vscjava.vscode-gradle",
+    "vscjava.vscode-maven"
+  ]
 }

.yamllint.yaml

@@ -0,0 +1,21 @@
+# 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.
+
+# https://yamllint.readthedocs.io/en/stable/configuration.html
+
+rules:
+  # Let's just check this only via .editorconfig instead
+  line-length: disable

common/common/src/main/java/dev/enola/common/io/mediatype/MarkdownMediaTypes.java

@@ -0,0 +1,52 @@
+/*
+ * 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.common.io.mediatype;
+
+import static com.google.common.net.MediaType.create;
+
+import com.google.common.base.Charsets;
+import com.google.common.collect.ImmutableMap;
+import com.google.common.collect.ImmutableSet;
+import com.google.common.net.MediaType;
+
+import java.util.Map;
+import java.util.Set;
+
+/**
+ * The "text/markdown" media type, as per <a href="https://www.rfc-editor.org/rfc/rfc7763.html">RFC
+ * 7763</a> (and <a href="https://www.rfc-editor.org/rfc/rfc7764.html">RFC 7764</a>).
+ */
+public class MarkdownMediaTypes implements MediaTypeProvider {
+
+    // TODO Distinguish https://commonmark.org from GFH et al. via a variant parameter; see
+    // https://www.iana.org/assignments/markdown-variants/markdown-variants.xhtml
+
+    public static final MediaType MARKDOWN_UTF_8 =
+            create("text", "markdown").withCharset(Charsets.UTF_8);
+    ;
+
+    @Override
+    public Map<String, MediaType> extensionsToTypes() {
+        return ImmutableMap.of("md", MARKDOWN_UTF_8);
+    }
+
+    @Override
+    public Map<MediaType, Set<MediaType>> knownTypesWithAlternatives() {
+        return ImmutableMap.of(MARKDOWN_UTF_8, ImmutableSet.of(create("text", "x-markdown")));
+    }
+}

common/common/src/main/java/dev/enola/common/io/mediatype/MediaTypeProvider.java

@@ -23,6 +23,9 @@
 import java.util.Set;
 
 public interface MediaTypeProvider {
+
+    // TODO An implementation based on enola.dev/mediaType Type YAML/binary!
+
     Map<MediaType, Set<MediaType>> knownTypesWithAlternatives();
 
     Map<String, MediaType> extensionsToTypes();

common/common/src/main/java/dev/enola/common/io/mediatype/YamlMediaType.java

@@ -21,7 +21,7 @@
 
 import com.google.common.base.Charsets;
 import com.google.common.collect.ImmutableMap;
-import com.google.common.collect.Sets;
+import com.google.common.collect.ImmutableSet;
 import com.google.common.net.MediaType;
 
 import java.util.Map;
@@ -41,7 +41,7 @@ public class YamlMediaType implements MediaTypeProvider {
     public Map<MediaType, Set<MediaType>> knownTypesWithAlternatives() {
         return ImmutableMap.of(
                 YAML_UTF_8,
-                Sets.newHashSet(
+                ImmutableSet.of(
                         create("text", "yaml"),
                         create("text", "x-yaml"),
                         create("application", "x-yaml")));

common/common/src/main/java/dev/enola/common/io/resource/DelegatingMultipartResource.java

@@ -0,0 +1,50 @@
+/*
+ * 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.common.io.resource;
+
+import com.google.common.collect.ImmutableMap;
+import com.google.common.collect.ImmutableSet;
+
+import java.io.IOException;
+
+public class DelegatingMultipartResource extends ReadableButNotWritableDelegatingResource
+        implements MultipartResource {
+
+    private final ImmutableMap<String, Resource> parts;
+
+    public DelegatingMultipartResource(
+            ReadableResource baseResource, ImmutableMap<String, Resource> parts)
+            throws IOException {
+        super(baseResource);
+        this.parts = parts;
+    }
+
+    @Override
+    public ImmutableSet<String> parts() {
+        return parts.keySet();
+    }
+
+    @Override
+    public Resource part(String name) {
+        var r = parts.get(name);
+        if (r == null)
+            throw new IllegalArgumentException(
+                    "Only " + parts().toString() + ", invalid part: " + name);
+        else return r;
+    }
+}

common/common/src/main/java/dev/enola/common/io/resource/EmptyResource.java

@@ -22,30 +22,38 @@
 import com.google.common.net.MediaType;
 
 import java.net.URI;
+import java.util.function.Supplier;
 
 /**
- * Resources which when read is always immediately EOF. Note that this is read-only, and
- * intentionally does not implement WritableResource; use e.g. {@link ResourceProviders#getResource}
- * with "empty:-" to get a wrapped implementation that implements writable but throws an error.
+ * Read-only resources which when read are always immediately EOF. This is a bit like /dev/null on
+ * *NIX OS for reading, but not for writing (because /dev/null ignores writes, whereas this fails).
  *
- * @see NullResource for an alternatives that returns 0s instead of EOF.
+ * @see NullResource for an alternatives that returns infinite 0s instead of EOF.
  */
-public class EmptyResource implements ReadableResource {
+public class EmptyResource implements ReadableButNotWritableResource {
     // TODO Perhaps rename this to VoidResource with void:/ URI?
 
     static final String SCHEME = "empty";
     private static final URI EMPTY_URI = URI.create(SCHEME + ":?");
-    private final MediaType mediaType;
 
-    private final URI uri;
+    private final MediaType mediaType;
+    private final Supplier<URI> uriSupplier;
+    private URI uri;
 
     public EmptyResource(MediaType mediaType) {
         this.mediaType = mediaType;
         this.uri = URIs.addMediaType(EMPTY_URI, mediaType);
+        this.uriSupplier = null;
+    }
+
+    public EmptyResource(MediaType mediaType, Supplier<URI> uriSupplier) {
+        this.mediaType = mediaType;
+        this.uriSupplier = uriSupplier;
     }
 
     @Override
     public URI uri() {
+        if (uri == null) uri = uriSupplier.get();
         return uri;
     }
 

common/common/src/main/java/dev/enola/common/io/resource/MarkdownResource.java

@@ -0,0 +1,64 @@
+/*
+ * 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.common.io.resource;
+
+import static com.google.common.net.MediaType.HTML_UTF_8;
+
+import static dev.enola.common.io.mediatype.YamlMediaType.YAML_UTF_8;
+
+import com.google.common.collect.ImmutableMap;
+
+import java.io.IOException;
+
+/**
+ * MarkdownResource is a {@link MultipartResource} which separates "Front Matter" (as {@link #FRONT}
+ * part, typically YAML structured data) and Markdown content (as {@link #BODY}) from the base
+ * resource.
+ *
+ * <p>The "frontmatter" is anything between 2 "---" lines at the very start of the file (if present,
+ * it's optional) and the "body" is everything that follows. Any HTML comment before the frontmatter
+ * is stripped (this is useful e.g. to ignore license headers).
+ *
+ * <p>This is very common de-facto standard format used by many Markdown tools. It may (TBC)
+ * originally have been <a href="https://jekyllrb.com/docs/front-matter/">introduced by Jekyll</a>.
+ */
+public class MarkdownResource extends RegexMultipartResource {
+
+    public static final String FIRST_COMMENT = "comment";
+    public static final String FRONT = "frontmatter";
+    public static final String BODY = "body";
+
+    private static final PartsDef PARTS =
+            new PartsDef(
+                    "(?s)^(?<"
+                            + FIRST_COMMENT
+                            + "><!--.*-->)?(\r?\n)*(===\r?\n(?<"
+                            + FRONT
+                            + ">.*)===\r?\n)?(\r?\n)*(?<"
+                            + BODY
+                            + ">.*)$",
+                    ImmutableMap.of(
+                            FIRST_COMMENT,
+                            HTML_UTF_8.withoutParameters(),
+                            FRONT,
+                            YAML_UTF_8.withoutParameters()));
+
+    public MarkdownResource(ReadableResource baseResource) throws IOException {
+        super(baseResource, PARTS);
+    }
+}