comm: complete migration to JSON.jl v1

This commit completes the migration to JSON.jl v1. As explained in
#300, JSON.jl v1 no longer supports out-of-box
deserialization for custom data types and now requires explicit
tags for each custom data type field (see
https://publish.obsidian.md/jetls/work/JETLS/Switch+JSON3.jl+to+JSON.jl+v1#2025-11-16).

This presents a significant challenge for LSP.jl, which uses the
`@interface` DSL for TypeScript-like type definitions, because
such tag generation must also be done through macro generation.
Without this approach, we would need to scatter `@tags` macros
and their associated `choosetype` definitions throughout the code
base, which should be very very tedious.

This commit further complicates the already complex `@interface`
implementation to implement such automatic tag generation.
While this macro has arguably become one of the most arcane
Julia macros in existence, it does function correctly.
Numerous tests have also been added.

Most importantly, completing the switch to JSON v1 provides the
following JSON communication performance improvements:

```julia
using LSP, JSON
function readlsp_JSON_v1(msg_str::AbstractString)
    lazyjson = JSON.lazy(msg_str)
    if hasproperty(lazyjson, :method)
        method = lazyjson.method[]
        if method isa String && haskey(LSP.method_dispatcher, method)
            return JSON.parse(lazyjson, LSP.method_dispatcher[method])
        end
        return JSON.parse(lazyjson, Dict{Symbol,Any})
    else # TODO parse to ResponseMessage?
        return JSON.parse(lazyjson, Dict{Symbol,Any})
    end
end
```
```julia
using JSON3, LSP
const Parsed = @NamedTuple{method::Union{Nothing,String}}
function readlsp_JSON3(msg_str::AbstractString)
    parsed = JSON3.read(msg_str, Parsed)
    parsed_method = parsed.method
    if parsed_method !== nothing
        if haskey(LSP.method_dispatcher, parsed_method)
            return JSON3.read(msg_str, LSP.method_dispatcher[parsed_method])
        end
        return JSON3.read(msg_str, Dict{Symbol,Any})
    else # TODO parse to ResponseMessage?
        return JSON3.read(msg_str, Dict{Symbol,Any})
    end
end
```
```julia
uri = LSP.URIs2.filepath2uri(abspath("src/JETLS.jl"))
s = """{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "textDocument/completion",
  "params": {
    "textDocument": {
      "uri": "$uri"
    },
    "position": {
      "line": 0,
      "character": 0
    },
    "workDoneToken": "workDoneToken",
    "partialResultToken": "partialResultToken"
  }
}""";
```
```julia-repl
julia> @benchmark readlsp_JSON3(s)
BenchmarkTools.Trial: 10000 samples with 1 evaluation per sample.
 Range (min … max):  363.792 μs …  1.154 ms  ┊ GC (min … max): 0.00% … 0.00%
 Time  (median):     379.958 μs              ┊ GC (median):    0.00%
 Time  (mean ± σ):   385.114 μs ± 16.805 μs  ┊ GC (mean ± σ):  0.00% ± 0.00%

   ▁▁  ▁ ▄▇█▇▆▆▅▅▅▅▄▄▄▄▃▃▃▂▂▂▂▂▁▁ ▁ ▁                          ▂
  ██████████████████████████████████████▇▇▇▇▇▇▇▇▆▅▆▆▆▆▅▆▇▆▅▆▆▅ █
  364 μs        Histogram: log(frequency) by time       447 μs <

 Memory estimate: 5.91 KiB, allocs estimate: 120.

julia> @benchmark readlsp_JSON_v1(s)
BenchmarkTools.Trial: 10000 samples with 1 evaluation per sample.
 Range (min … max):  11.625 μs … 113.000 μs  ┊ GC (min … max): 0.00% … 0.00%
 Time  (median):     12.375 μs               ┊ GC (median):    0.00%
 Time  (mean ± σ):   12.658 μs ±   1.933 μs  ┊ GC (mean ± σ):  0.00% ± 0.00%

   ▃▄▅▅▆██▇█▅▅▄▃▂▂                                             ▂
  ▇██████████████████▇▇▆▇▆▅▇▅▅▆▆▆▇▆▆▇▇▆▇▆▆▇▇▅▇██▆▇▅▅▆▆▆▅▅▄▄▂▅▆ █
  11.6 μs       Histogram: log(frequency) by time      17.4 μs <

 Memory estimate: 4.53 KiB, allocs estimate: 84.
```

---

- renamed `LSP/src/utils` to `LSP/src/DSL`
- also added precompilation statements for better FTTJ
- added docstrings

Author: aviatesk

.gitignore

@@ -6,3 +6,4 @@ Manifest-*.toml
 **/.JETLSConfig.toml
 *.vsix
 docs/build/
+LocalPreference.toml

JSONRPC/src/JSONRPC.jl

@@ -63,7 +63,7 @@ function readmsg(io::IO, method_dispatcher)
     lazyjson = JSON.lazy(msg_str)
     if hasproperty(lazyjson, :method)
         method = lazyjson.method[]
-        if haskey(method_dispatcher, method)
+        if method isa String && haskey(method_dispatcher, method)
             return JSON.parse(lazyjson, method_dispatcher[method])
         end
         return JSON.parse(lazyjson, Dict{Symbol,Any})

LSP/Project.toml

@@ -8,8 +8,12 @@ projects = ["test"]
 
 [deps]
 JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
+PrecompileTools = "aea7be01-6a6a-4083-8856-8a6e6704d82a"
+Preferences = "21216c6a-2e73-6563-6e65-726566657250"
 StructUtils = "ec057cc2-7a8d-4b58-b3b3-92acb9f63b42"
 
 [compat]
 JSON = "1.3"
+PrecompileTools = "1.3.3"
+Preferences = "1.5.0"
 StructUtils = "2.6.0"

LSP/src/DSL/interface.jl

@@ -1,3 +1,45 @@
+"""
+    @namespace NamespaceName::Type begin
+        CONSTANT_NAME = value
+        ...
+    end
+
+Creates a Julia module containing typed constants that correspond to TypeScript `namespace`
+definitions from the LSP specification.
+
+# Type references
+
+Due to the design that mimics TypeScript `namespaces` using Julia's module system,
+namespace types must be referenced with the `.Ty` suffix:
+
+```julia
+@namespace SignatureHelpTriggerKind::Int begin
+    Invoked = 1
+    TriggerCharacter = 2
+    ContentChange = 3
+end
+
+@interface SignatureHelpContext begin
+    ...
+    # Use as type annotation
+    triggerKind::SignatureHelpTriggerKind.Ty
+    ...
+end
+```
+
+This is a constraint of Julia's module scoping rules, where constants and type aliases
+within modules cannot be accessed without explicit qualification.
+
+# Implementation details
+
+The macro generates:
+1. A Julia module with the specified namespace name
+2. Constants with the specified type and values
+3. A `Ty` type alias equal to the specified type for convenient type references
+4. Automatic export of the namespace name to the parent module
+
+See also: [`@interface`](@ref)
+"""
 macro namespace(exs...)
     nexs = length(exs)
     nexs == 2 || error("`@namespace` expected 2 arguments: ", exs)

LSP/src/utils/namespace.jl LSP/src/DSL/namespace.jlLSP/src/utils/namespace.jl renamed to LSP/src/DSL/namespace.jl

@@ -3,17 +3,33 @@ module LSP
 using StructUtils: StructUtils
 using JSON: JSON
 
+using Preferences: Preferences
+const LSP_DEV_MODE = Preferences.@load_preference("LSP_DEV_MODE", false)
+
 include("URIs2/URIs2.jl")
 using ..URIs2: URI
 
 const exports = Set{Symbol}()
 const method_dispatcher = Dict{String,DataType}()
 
-include("utils/interface.jl")
-include("utils/namespace.jl")
+# NOTE `Null` and `URI` are referenced directly from interface.jl, so it should be defined before that.
 
-include("base-protocol.jl")
+"""
+A special object representing `null` value.
+When used as a field that might be omitted in the serialized JSON (i.e. the field can be `nothing`),
+the key-value pair appears as `null` instead of being omitted.
+This special object is specifically intended for use in `ResponseMessage`.
+"""
+StructUtils.@nonstruct struct Null end
+const null = Null()
+Base.show(io::IO, ::Null) = print(io, "null")
+StructUtils.lower(::Null) = JSON.Null()
+push!(exports, :Null, :null)
+
+include("DSL/interface.jl")
+include("DSL/namespace.jl")
 
+include("base-protocol.jl")
 include("basic-json-structures.jl")
 include("lifecycle-messages/register-capability.jl")
 include("lifecycle-messages/unregister-capability.jl")
@@ -49,4 +65,6 @@ end
 export
     method_dispatcher
 
+include("precompile.jl")
+
 end # module LSP

LSP/src/LSP.jl

@@ -1,17 +1,6 @@
 # Base types
 # =========
 
-"""
-A special object representing `null` value.
-When used as a field that might be omitted in the serialized JSON (i.e. the field can be `nothing`),
-the key-value pair appears as `null` instead of being omitted.
-This special object is specifically intended for use in `ResponseMessage`.
-"""
-struct Null end
-const null = Null()
-StructUtils.lower(::Null) = JSON.Null()
-push!(exports, :Null, :null)
-
 const boolean = Bool
 const string = String
 

LSP/src/base-protocol.jl

@@ -234,7 +234,6 @@ end
 export CompletionData
 
 @interface CompletionItem begin
-
     """
     The label of this completion item.
 

LSP/src/language-features/completions.jl

@@ -28,4 +28,4 @@ end
 
 @interface DefinitionResponse @extends ResponseMessage begin
     result::Union{Location, Vector{Location}, Vector{LocationLink}, Null, Nothing}
-end
+end

LSP/src/language-features/definition.jl

@@ -0,0 +1,70 @@
+function readlsp(msg_str::AbstractString)
+    lazyjson = JSON.lazy(msg_str)
+    if hasproperty(lazyjson, :method)
+        method = lazyjson.method[]
+        if haskey(method_dispatcher, method)
+            return JSON.parse(lazyjson, method_dispatcher[method])
+        end
+        return JSON.parse(lazyjson, Dict{Symbol,Any})
+    else # TODO parse to ResponseMessage?
+        return JSON.parse(lazyjson, Dict{Symbol,Any})
+    end
+end
+writelsp(x) = JSON.json(x; omit_null=true)
+
+function test_roundtrip(f, s::AbstractString, Typ)
+    x = JSON.parse(s, Typ)
+    f(x)
+    s′ = writelsp(x)
+    x′ = JSON.parse(s′, Typ)
+    f(x′)
+end
+
+using PrecompileTools
+
+@setup_workload let
+    uri = LSP.URIs2.filepath2uri(abspath(@__FILE__))
+    @compile_workload let
+        test_roundtrip("""{
+                "jsonrpc": "2.0",
+                "id":0, "method":"textDocument/completion",
+                "params": {
+                    "textDocument": {
+                        "uri": "$uri"
+                    },
+                    "position": {
+                        "line": 0,
+                        "character": 0
+                    },
+                    "workDoneToken": "workDoneToken",
+                    "partialResultToken": "partialResultToken"
+                }
+            }""", CompletionRequest) do req
+            @assert req isa CompletionRequest
+        end
+        test_roundtrip("""{
+                "jsonrpc": "2.0",
+                "id": 0,
+                "method": "completionItem/resolve",
+                "params": {
+                    "label": "label",
+                    "textEdit": {
+                        "range": {
+                            "start": {
+                                "line": 0,
+                                "character": 0
+                            },
+                            "end": {
+                                "line": 0,
+                                "character": 0
+                            }
+                        },
+                        "newText": "newText"
+                    }
+                }
+            }""", CompletionResolveRequest) do req
+            @assert req isa CompletionResolveRequest
+            @assert req.params.textEdit isa TextEdit
+        end
+    end
+end