@zenwave360/lsp-js 0.1.0-next.12.1 → 0.1.0-next.14.1

package/README.md

@@ -51,6 +51,8 @@ hover, definition, references, document symbols and formatting. `capabilities.ex
 - `customRequests`: `string[]`, the `zenwave/*` requests this server answers. The list is built from the
   server's handler registration, so a client can rely on it. A request that is not listed is answered
   with JSON-RPC `-32601`. lsp-jvm additionally exposes workspace concept and status requests.
+- `previewModes`: `true` when `zenwave/preview` accepts its additive `mode` parameter and grouped diagram representations.
+- `organizeModes`: `true` when `zenwave/organizeZflServices` accepts `mode` (`full`, the default, or `additive`).
 
 ## Custom requests
 
@@ -58,9 +60,9 @@ hover, definition, references, document symbols and formatting. `capabilities.ex
 | --- | --- | --- |
 | `zenwave/hierarchy` | `{ uri }` | hierarchy nodes `{ id, label, kind, language, sourceUri, sourceRange, children, relatedResources, uiHints, viewNodeIds }[]` |
 | `zenwave/forwardReferences`, `zenwave/reverseReferences` | `{ uri, semanticId }` | navigation targets |
-| `zenwave/organizeZflServices` | `{ uri }` | the reorganised ZFL text, or `null` |
+| `zenwave/organizeZflServices` | `{ uri, mode?: "full" \| "additive" }` | the reorganised ZFL text, or `null` |
 | `zenwave/eventFlowViews` | `{ textDocument: { uri } }` | `{ flowGraph, serviceGraph }`: dsl-kotlin's laid-out flow and service view models, each with its `schema` (`zfl.eventflow.view@1`, `zfl.services.view@1`) |
-| `zenwave/preview` | `{ textDocument: { uri }, sequenceRenderMode?: "SEPARATE_VARIANTS" \| "ALT_BLOCKS" \| "AUTO" }` | `{ representations: { id, title, format: "MARKDOWN" \| "MERMAID" \| "HTML", content }[], defaultRepresentationId }` |
+| `zenwave/preview` | `{ textDocument: { uri }, mode?: "docs" \| "diagrams", sequenceRenderMode?: "SEPARATE_VARIANTS" \| "ALT_BLOCKS" \| "AUTO" }` | `{ representations: { id, title, format: "MARKDOWN" \| "MERMAID" \| "HTML", content, group? }[], defaultRepresentationId }` |
 | `zenwave/symbolAt` | `{ textDocument: { uri }, position: { line, character } }` | `{ uri, semanticId, range? }`, the input of the two reference requests, or `null` when nothing is declared or referenced there |
 
 `zenwave/hierarchy` answers whether or not the document is open. An open document is answered from the
@@ -74,10 +76,38 @@ groups of the same document's `zenwave/eventFlowViews` that stand for the node's
 `event:OrderCreated`, `event:OrderCreated@Orders>OrderService`, `group:Orders>OrderService`, `policy:…`); it
 is empty when the diagram has no counterpart.
 
-`zenwave/preview` answers for ZDL (one Mermaid `class-diagram`) and ZFL (a `flowchart`, then one
-`sequence:<outcome>:<index>` per end outcome; the first sequence is the default). `sequenceRenderMode`
+`zenwave/organizeZflServices` defaults to `mode: "full"`, which rebuilds the systems block from the flows.
+`mode: "additive"` adds what the flows use and removes nothing. A document the server cannot process answers
+`null` in either mode.
+
+`zenwave/preview` defaults to `mode: "docs"`, so it answers for ZDL (one `MARKDOWN` representation `domain`, "Domain model": the model's page with its
+diagrams as `mermaid` fences), `.zw` (one `MARKDOWN` representation `configuration`, "Plugin configuration": the `config`
+block and each plugin with what it is for and its resolved configuration; the document's language id is `zw`, or its
+URI ends in `.zw`) and ZFL (a `flowchart`, then one `sequence:<outcome>:<index>` per end outcome; the first sequence is
+the default). What a model wrote is escaped in the Markdown, so a `<script>` shows as text. `sequenceRenderMode`
 defaults to `ALT_BLOCKS`. Null properties are omitted from every result.
 
+For a ZDL, `mode: "diagrams"` returns only individual `MERMAID` diagrams. Every representation has a `group` of
+`Services`, `Aggregates`, `State Machines`, `Events`, `Commands` or `Other entities`; absent kinds have no representation.
+
+### Plugin catalogue
+
+The `.zw` page describes each plugin (what it is for, what its options mean) from a plugin catalogue, the JSON
+the ZenWave SDK reports for `-h json`, in the shape of the VS Code extension's `sdk-plugin-catalogue.json`
+(`{ source, version, plugins: [...] }`; fields the server does not know are ignored). The server ships its own copy,
+embedded in the bundle, so it works with no file read (the Web Worker too), and uses the last valid catalogue a
+client sent. The copy is generated by `scripts/generate-plugin-catalogue.mjs` from a named SDK build (its
+`source`/`version`, today `ZenWave SDK 2.8.0-SNAPSHOT`) and parsed the first time a `.zw` is previewed.
+
+- At initialisation: `initializationOptions.pluginCatalogue`, the catalogue as a JSON object.
+- At any time: the notification `zenwave/pluginCatalogue` with params `{ catalogue: <JSON object> }`. It is advertised
+  in `capabilities.experimental.customNotifications` (`["zenwave/pluginCatalogue"]`), beside `customRequests`.
+
+The next `zenwave/preview` uses it (previews are not cached). A plugin that is not in the catalogue still shows its
+name and resolved configuration, without a description. A catalogue that is not an object, is not JSON or has no
+`plugins` array is ignored, the previous one stays, and the server logs a warning with `window/logMessage`;
+it never fails initialisation.
+
 Both visualisation requests read open documents. When a document cannot answer they fail with JSON-RPC
 `-32803` and `data.kind`: `documentUnreadable` (a syntax error; `data.diagnostics` holds LSP diagnostics),
 `documentNotFound` (not open) or `unsupportedDocument` (a kind of document the request does not cover).
@@ -87,7 +117,7 @@ The worker bundle carries elkjs for the flow layout. elkjs' in-process layout wo
 the Web Worker's `onmessage` when it detects a worker global; `build.mjs` disables that detection when bundling,
 and the build fails if an elkjs upgrade changes it.
 
-Initialization options take the form `{ zenwave: { configUri?, projectManifestUri? } }`.
+Initialization options take the form `{ zenwave: { configUri?, projectManifestUri? }, pluginCatalogue? }`.
 
 ## Building