Support JSON and JSONC catalog files.

[wfouche]

JSONC is JSON extended for use as a configuration data file format. Comments are useful in configuration files, and also allow for sections of the config to be commented out to temporarily or permanently disable parts of the configuration.

JSONC is supported by IntelliJ and VSCode.

Example JSONC file.

{
  // This is a comment
  "name": "Project",
  "version": "1.0.0"   // Another comment
  "settings": {
    "enabled": true
  }
}

Comments can be added to jbang-catalog.json files because the gson parser silently ignores comments by default. Howver, the only remaining issue is that VSCode and IntelliJ displays formatting errors if comments are included in a JSON file.

Renaming the file to jbang-catalog.jsonc resolves this issue.

Only one of the catalog files should exist: either jbang-catalog.json or jbang-catalog.jsonc, but not both.

[wfouche]

Test program that fires off two HTTP requests in parallel to check if a JSON or JSONC catalog file exists.

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.List;
import java.util.Optional;
import java.util.concurrent.CompletableFuture;

public class JBangCatalogFinder {

    private static final HttpClient CLIENT = HttpClient.newHttpClient();

    public static void main(String[] args) {
        String baseUrl = "http://<my-host>/files/";
        
        findExistingCatalogUrl(baseUrl).ifPresentOrElse(
            url -> System.out.println("Found valid catalog at: " + url),
            () -> System.err.println("No catalog found (404 on both .json and .jsonc)")
        );
    }

    /**
     * Fires requests for both possible catalog extensions.
     * @return An Optional containing the URL of the first file found with a 200 OK status.
     */
    public static Optional<String> findExistingCatalogUrl(String baseUrl) {
        List<String> targets = List.of(baseUrl + "jbang-catalog.json", baseUrl + "jbang-catalog.jsonc");

        // Map URLs to async requests
        List<CompletableFuture<String>> searches = targets.stream()
            .map(url -> {
                HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create(url))
                    .method("HEAD", HttpRequest.BodyPublishers.noBody()) // HEAD is faster if we just need to check existence
                    .build();

                return CLIENT.sendAsync(request, HttpResponse.BodyHandlers.discarding())
                    .thenApply(res -> res.statusCode() == 200 ? url : null);
            })
            .toList();

        // Wait for all to finish, then find the first non-null result
        return CompletableFuture.allOf(searches.toArray(new CompletableFuture[0]))
            .thenApply(v -> searches.stream()
                .map(CompletableFuture::join)
                .filter(url -> url != null)
                .findFirst()
            ).join();
    }
}

[maxandersen]

If I recall we allow comments in our json files? Is that failing ?

[maxandersen]

I recall we have issue that on rewrite the comments are lost. But that's separate issue :)

[wfouche]

If I recall we allow comments in our json files? Is that failing ?

Comments can be added to the jbang-catalog.json files, BUT most IDEs complain about the resulting file then not being a valid JSON file.

JBang is using JSON + Comments which is JSCONC for catalog files. It therefore better to allow the file extension to be .jsonc and then the errors reporting by IDEs will also disappear.

[wfouche]

Many projects on Github support JSON with Comments (JSONC), but only a few of them use the .jsonc file extension for JSON with Comments data.

[wfouche]

The simplest option might just be to configure VSCode to assume that "jbang-catalog.json" files are JSONC files.

VSCode settings.json

{
    "files.associations": {
        "jbang-catalog.json": "jsonc"
    }
}

This is something the JBang plugins for VSCode and IntelliJ should configure automatically; but they don't at the moment.

[wfouche]

PR submitted for the VSCode JBang plugin

• fix: use JSONC for jbang-catalog.json files jbang-vscode#185

[wfouche]

IntelliJ can be configured to allow comments in JSON files.

But this is done globally, and is not recommended. Better to associated jbang-catalog.json files with JSON5.

Need to check whether this option can be configured automatically by the JBang plugin for IntelliJ.

[wfouche]

PR submitted for the IntelliJ Jbang plugin:

• fix: allow comments in jbang-catalog.json files jbang-idea#144