Add entrypoin to generate plugin schema

Signed-off-by: Ben Sherman <bentshermann@gmail.com>

Author: bentsherman

adrs/00-template.md

@@ -0,0 +1,79 @@
+# [short title of solved problem and solution]
+
+- Authors: [who wrote the ADR]
+- Status: [draft | proposed | rejected | accepted | deprecated | … | superseded by [xxx](xxx.md)]
+- Deciders: [list everyone involved in the decision]  <!-- optional - to be formalised -->
+- Date: [YYYY-MM-DD when the decision was last updated]
+- Tags: [space and/or comma separated list of tags]
+
+Technical Story: [description | ticket/issue URL] <!-- optional -->
+
+## Summary 
+
+Quick description of the problem and the context. Should not take more than 2-3 lines.
+
+## Problem Statement
+
+Description of the technical problem to solve or to decision to make. This should be concise but provide all
+required details and the context related to the technical decision to be taken.
+
+## Goals or Decision Drivers
+
+Depending the context define clearly what are the goals or what are the most important decision drivers.
+
+- [driver 1, e.g., a force, facing concern, …]
+- [driver 2, e.g., a force, facing concern, …]
+- … <!-- numbers of drivers can vary -->
+
+## Non-goals
+
+Define what's out of the scope of this ADR.
+
+## Considered Options <!-- optional -->
+
+- [option 1]
+- [option 2]
+- [option 3]
+- … <!-- numbers of options can vary -->
+
+
+## Pros and Cons of the Options <!-- optional -->
+
+### [option 1]
+
+[example | description | pointer to more information | …] <!-- optional -->
+
+- Good, because [argument a]
+- Good, because [argument b]
+- Bad, because [argument c]
+- … <!-- numbers of pros and cons can vary -->
+
+### [option 2]
+
+[example | description | pointer to more information | …] <!-- optional -->
+
+- Good, because [argument a]
+- Good, because [argument b]
+- Bad, because [argument c]
+- … <!-- numbers of pros and cons can vary -->
+
+
+## Solution or decision outcome
+
+Summarize the solution or decision outcome in one-two lines.
+
+## Rationale & discussion
+
+Describe the solution or the decision outcome discussing how decision drivers have been applied
+and how it matches the declared goals. This section is expected to be concise though providing comprehensive
+description of the technical solution and covering all uncertainty or ambiguous points.
+
+## Links <!-- optional -->
+
+- [Link type](link to adr) <!-- example: Refined by [xxx](yyyymmdd-xxx.md) -->
+- … <!-- numbers of links can vary -->
+
+## More information
+
+- [What is an ADR and why should you use them](https://github.com/thomvaill/log4brains/tree/master#-what-is-an-adr-and-why-should-you-use-them)
+- [ADR GitHub organization](https://adr.github.io/)

adrs/01-plugin-schema.md

@@ -0,0 +1,150 @@
+# Plugin Schema
+
+- Authors: Ben Sherman
+- Status: accepted
+- Deciders: Ben Sherman, Paolo Di Tommaso
+- Date: 2025-09-22
+- Tags: plugins
+
+## Summary 
+
+Provide a way for external systems to understand key information about third-party plugins.
+
+## Problem Statement
+
+Nextflow plugins need a way to statically declare extensions to the Nextflow language so that external systems can extract information about a plugin without loading it in the JVM.
+
+Primary use cases:
+
+- The Nextflow language server needs to know about any config scopes, custom functions, etc, defined by a plugin, in order to recognize them in Nextflow scripts and config files
+
+- The Nextflow plugin registry (or other user interfaces) can use this information to provide API documentation.
+
+## Goals or Decision Drivers
+
+- External systems (e.g. language server) need to be able to understand plugins without having to load them in the JVM.
+
+## Non-goals
+
+- Defining the schema for the core runtime and core plugins: these definitions are handled separately, although they may reuse some of the structures used for plugin schemas.
+
+## Considered Options
+
+### Nextflow plugin system
+
+Require external systems to use Nextflow's plugin system to load plugins at runtime in order to extract information about them.
+
+- **Pro:** Allows any information to be extracted since the entire plugin is loaded
+
+- **Con:** Requires the entire Nextflow plugin system to be reused or reimplemented. Not ideal for Java applications since the plugin system is implemented in Groovy, incompatible with non-JVM applications
+
+- **Con:** Requires plugins to be downloaded, cached, loaded in the JVM, even though there is no need to use the plugin.
+
+### Plugin schema
+
+Define a plugin schema for every plugin release which is stored and served by the plugin registry as JSON.
+
+- **Pro:** Allows any system to access plugin definitions through a standard JSON format. Does not require downloading plugins or loading them into a JVM.
+
+- **Con:** Requires the plugin schema to be generated at build-time and stored in the plugin registry.
+
+- **Con:** Requires a standard JSON format across all versions of Nextflow, the language server, and third-party plugins.
+
+## Solution
+
+Define a plugin schema for every plugin release which is stored and served by the plugin registry as JSON.
+
+- Plugin developers only need to define [extension points](https://nextflow.io/docs/latest/plugins/developing-plugins.html#extension-points) as usual, and the Gradle plugin will extract the plugin schema and store it in the plugin registry as part of each plugin release.
+
+- The language server can retrieve plugin schemas based on the `plugins` block in a config file.
+
+A plugin schema consists of a list of *definitions*. Each definition has a *type* and a *spec*.
+
+Example:
+
+```json
+[
+    {
+        "type": "ConfigScope",
+        "spec": {
+            // ...
+        }
+    },
+    {
+        "type": "Function",
+        "spec": {
+            // ...
+        }
+    },
+]
+```
+
+The following types of definitions are allowed:
+
+**ConfigScope**
+
+Defines a top-level config scope. The spec consists of a *name*, an optional *description*, and *children*.
+
+The children should be a mapping of names to schemas, where each name denotes a nested config scope or option. The following nested schemas are allowed:
+
+- **ConfigOption**: Defines a config option. The spec consists of a *description* and *type*.
+
+- **ConfigScope**: Defines a nested config scope, using the same schema as for top-level scopes.
+
+Example:
+
+```json
+{
+    "type": "ConfigScope",
+    "spec": {
+        "name": "hello",
+        "description": "The `hello` scope controls the behavior of the `nf-hello` plugin.",
+        "children": {
+            "message": {
+                "type": "ConfigOption",
+                "spec": {
+                    "description": "Message to print to standard output when the plugin is enabled.",
+                    "type": "String"
+                }
+            }
+        }
+    }
+}
+```
+
+**Factory**
+
+Defines a channel factory that can be included in Nextflow scripts. The spec is the same as for functions.
+
+**Function**
+
+Defines a function that can be included in Nextflow scripts. The spec consists of a *name*, an optional *description*, a *return type*, and a list of *parameters*. Each parameter consists of a *name* and a *type*.
+
+Example:
+
+```json
+{
+    "type": "Function",
+    "spec": {
+        "name": "sayHello",
+        "description": "Say hello to the given target",
+        "returnType": "void",
+        "parameters": [
+            {
+                "name": "target",
+                "type": "String"
+            }
+        ]
+    }
+}
+```
+
+**Operator**
+
+Defines a channel operator that can be included in Nextflow scripts. The spec is the same as for functions.
+
+## Rationale & discussion
+
+Now that there is a Gradle plugin for building Nextflow plugins, as well as a registry to publish and retrieve plugins, the generation and retrieval of plugin schemas can be implemented in a way that is transparent to plugin developers.
+
+The primary challenge is to ensure that the schema of the plugin schema (i.e. the meta-schema) remains consistent across Nextflow versions, or is versioned so that external systems can understand multiple versions over time as needed.

modules/nextflow/src/main/groovy/nextflow/plugin/schema/ConfigSchema.groovy

@@ -75,21 +75,15 @@ class ConfigSchema {
             type: 'ConfigScope',
             spec: [
                 name: scopeName,
-                description: withLink(scopeName, description),
+                description: description,
                 children: children
             ]
         ]
     }
 
-    private static String withLink(String scopeName, String description) {
-        return scopeName
-            ? "$description\n\n[Read more](https://nextflow.io/docs/latest/reference/config.html#$scopeName)\n"
-            : description
-    }
-
     private static Object fromType(ClassNode cn) {
         final name = Types.getName(cn.getTypeClass())
-        if( cn.isUsingGenerics() ) {
+        if( cn.getGenericsTypes() != null ) {
             final typeArguments = cn.getGenericsTypes().collect { gt -> fromType(gt.getType()) }
             return [ name: name, typeArguments: typeArguments ]
         }

modules/nextflow/src/main/groovy/nextflow/plugin/schema/FunctionSchema.groovy

@@ -27,6 +27,7 @@ class FunctionSchema {
 
     static Map<String,?> of(Method method, String type) {
         final name = method.getName()
+        final description = method.getAnnotation(Description)?.value()
         final returnType = fromType(method.getReturnType())
         final parameters = method.getParameters().collect { param ->
             [
@@ -39,6 +40,7 @@ class FunctionSchema {
             type: type,
             spec: [
                 name: name,
+                description: description,
                 returnType: returnType,
                 parameters: parameters
             ]
@@ -51,7 +53,7 @@ class FunctionSchema {
 
     private static Object fromType(ClassNode cn) {
         final name = Types.getName(cn.getTypeClass())
-        if( cn.isUsingGenerics() ) {
+        if( cn.getGenericsTypes() != null ) {
             final typeArguments = cn.getGenericsTypes().collect { gt -> fromType(gt.getType()) }
             return [ name: name, typeArguments: typeArguments ]
         }