Merge branch 'main' into feat/synthesized-sources

Co-authored-by: koenbeuk <2912652+koenbeuk@users.noreply.github.com>

Author: Copilot

src/Docs/Playground.Wasm/Program.cs

@@ -11,10 +11,9 @@
 builder.RootComponents.RegisterCustomElement<PlaygroundHost>("expressive-playground");
 
 // BaseAddress must point to the playground's own directory (where _framework/
-// lives) so PlaygroundReferences can fetch reference DLLs. When the web
-// component is hosted on a VitePress page, HostEnvironment.BaseAddress is
-// the docs site root — not the playground subdirectory. We detect this by
-// checking whether the base ends with /playground/.
+// lives) so PlaygroundReferences can fetch reference DLLs. On a VitePress page
+// HostEnvironment.BaseAddress is the docs site root, not the playground
+// subdirectory — detect by checking whether the base ends with /playground/.
 var baseAddress = builder.HostEnvironment.BaseAddress;
 if (!baseAddress.TrimEnd('/').EndsWith("/_playground", StringComparison.OrdinalIgnoreCase)
     && !baseAddress.TrimEnd('/').EndsWith("/playground", StringComparison.OrdinalIgnoreCase))
@@ -29,8 +28,6 @@
 
 var host = builder.Build();
 
-// Register Monaco completion + hover providers via our JS interop module.
-// The DotNetObjectReference callbacks dispatch to PlaygroundLanguageServices.
 var runtime = host.Services.GetRequiredService<PlaygroundRuntime>();
 var jsRuntime = host.Services.GetRequiredService<IJSRuntime>();
 
@@ -40,10 +37,8 @@
 
 await host.RunAsync();
 
-/// <summary>
-/// Bridge object exposed to JS via DotNetObjectReference. Monaco's completion
-/// and hover providers call back into these [JSInvokable] methods.
-/// </summary>
+// Bridge object exposed to JS via DotNetObjectReference. Monaco's completion
+// and hover providers call back into these [JSInvokable] methods.
 internal sealed class MonacoLanguageProviderBridge
 {
     private readonly PlaygroundRuntime _runtime;

src/Docs/Playground.Wasm/Services/ManagedSqliteStub.cs

@@ -1,16 +1,12 @@
-// ManagedSqliteStub — a fully-managed SQLitePCL.ISQLite3Provider implementation
-// that EF Core can interrogate at startup *without* needing the native sqlite3
-// engine. The playground only ever calls ToQueryString() on a queryable; that
-// path goes through EF Core's relational query translator and never executes
-// real SQL, but the SqliteUpdateSqlGenerator constructor probes
-// connection.ServerVersion → SQLitePCL.raw.sqlite3_libversion() during DI
-// graph construction. This stub answers the metadata calls that EF Core makes
-// during model build, and throws NotSupportedException for anything that would
-// require running real queries.
+// Fully-managed SQLitePCL.ISQLite3Provider so EF Core can be interrogated at
+// startup without the native sqlite3 engine. The playground only calls
+// ToQueryString() — never executes real SQL — but SqliteUpdateSqlGenerator's
+// ctor probes connection.ServerVersion → sqlite3_libversion() during DI graph
+// construction. This stub answers the metadata calls EF Core makes during
+// model build; everything else throws.
 //
-// The interface has 152 methods (utf8z is a ref struct so DispatchProxy can't
-// be used). Most just throw — only a handful of "metadata" calls have real
-// answers. Generated from reflection at design time and committed.
+// utf8z is a ref struct so DispatchProxy can't be used; the 152 methods are
+// generated from reflection at design time and committed.
 
 #pragma warning disable IDE0060 // Unused parameters — interface forces us to declare them
 
@@ -20,10 +16,7 @@ namespace ExpressiveSharp.Docs.Playground.Wasm.Services;
 
 public sealed class ManagedSqliteStub : ISQLite3Provider
 {
-    /// <summary>
-    /// Registers this stub as the global SQLitePCL provider. Idempotent.
-    /// Must be called before any DbContext that uses Sqlite.Core is constructed.
-    /// </summary>
+    // Idempotent — must be called before any DbContext using Sqlite.Core is constructed.
     public static void Register()
     {
         try
@@ -32,37 +25,30 @@ public static void Register()
         }
         catch (System.InvalidOperationException)
         {
-            // SetProvider throws if a provider is already registered. Tolerate
-            // double-registration so the stub can be installed eagerly from
-            // multiple host entrypoints (Program.cs, test setup, etc).
+            // SetProvider throws if a provider is already registered; tolerate
+            // double-registration from multiple host entrypoints.
         }
     }
 
-    // ── Metadata calls EF Core makes during DbContext init ─────────────────
-
-    // Reported as the SQLite library version. EF Core uses this for feature
-    // detection (RETURNING clause support added in 3.35). Reporting a recent
-    // version unlocks all relational translator features.
+    // EF Core uses libversion for feature detection (RETURNING added in 3.35).
+    // Reporting a recent version unlocks all relational translator features.
     public utf8z sqlite3_libversion() => utf8z.FromString("3.45.0");
 
-    // Companion to libversion. Format is major*1_000_000 + minor*1_000 + patch.
+    // Format is major*1_000_000 + minor*1_000 + patch.
     public int sqlite3_libversion_number() => 3045000;
 
     public utf8z sqlite3_sourceid() => utf8z.FromString("managed-stub-no-sourceid");
 
-    // 1 = single-threaded. WASM is single-threaded anyway.
     public int sqlite3_threadsafe() => 1;
 
     public string GetNativeLibraryName() => "managed-stub";
 
-    // SQLitePCL.raw initializes by calling these once. They must succeed.
+    // SQLitePCL.raw calls these once during init — they must succeed.
     public int sqlite3_initialize() => 0; // SQLITE_OK
     public int sqlite3_shutdown() => 0;
     public int sqlite3_config_log(global::SQLitePCL.delegate_log @func, global::System.Object @v) => 0;
     public int sqlite3_enable_shared_cache(int @enable) => 0;
 
-    // ── Everything else throws ─────────────────────────────────────────────
-
     private static System.Exception NotSupported(string method) =>
         new System.NotSupportedException(
             $"ManagedSqliteStub does not implement '{method}'. " +

src/Docs/Playground.Wasm/Services/MonacoTypes.cs

@@ -1,8 +1,7 @@
 namespace ExpressiveSharp.Docs.Playground.Wasm.Services;
 
-// DTOs for JSInterop serialization with Monaco editor.
-// These replace the BlazorMonaco C# types with plain records
-// that serialize cleanly to/from the Monaco JS API.
+// DTOs for JSInterop with Monaco editor; replace BlazorMonaco's types with
+// plain records that serialize cleanly to/from the Monaco JS API.
 
 public sealed class MonacoPosition
 {
@@ -50,7 +49,6 @@ public sealed class MonacoMarkerData
     public int EndColumn { get; set; }
 }
 
-// Completion types
 public sealed class MonacoCompletionList
 {
     public List<MonacoCompletionItem> Suggestions { get; set; } = new();
@@ -68,7 +66,6 @@ public sealed class MonacoCompletionItem
     public MonacoRange? Range { get; set; }
 }
 
-// Hover types
 public sealed class MonacoHover
 {
     public List<MonacoMarkdownString> Contents { get; set; } = new();
@@ -81,7 +78,7 @@ public sealed class MonacoMarkdownString
     public bool IsTrusted { get; set; }
 }
 
-// Monaco CompletionItemKind enum values (matching monaco.languages.CompletionItemKind)
+// Values match monaco.languages.CompletionItemKind.
 public static class MonacoCompletionItemKind
 {
     public const int Method = 0;
@@ -109,7 +106,7 @@ public static class MonacoCompletionItemKind
     public const int TypeParameter = 24;
 }
 
-// Monaco MarkerSeverity values (matching monaco.MarkerSeverity)
+// Values match monaco.MarkerSeverity.
 public static class MonacoMarkerSeverity
 {
     public const int Hint = 1;

src/Docs/Playground.Wasm/Services/PlaygroundLanguageServices.cs

@@ -1,12 +1,10 @@
-// PlaygroundLanguageServices — long-lived AdhocWorkspace that backs Monaco's
-// completion + hover providers. Separate from SnippetCompiler (which builds
-// fresh CSharpCompilations per keystroke for the run path); the workspace's
-// incremental semantic model gives sub-ms per-keystroke completion.
-//
-// Architecture inspired by DotNetLab/src/Compiler/LanguageServices.cs (MIT):
-// one AdhocWorkspace, one Project, one Document per <expressive-playground>
-// instance routed by Monaco model URI. The DefaultPersistentStorageConfiguration
-// cctor PNSE is bypassed by the WorkspaceShim project — see its header.
+// Long-lived AdhocWorkspace backing Monaco's completion + hover providers; the
+// incremental semantic model gives sub-ms per-keystroke completion. Separate
+// from SnippetCompiler, which builds fresh CSharpCompilations per run.
+// One Document per <expressive-playground> instance, routed by Monaco model
+// URI. The DefaultPersistentStorageConfiguration cctor PNSE on WASM is bypassed
+// by the WorkspaceShim project — see its header.
+// Architecture inspired by DotNetLab/src/Compiler/LanguageServices.cs (MIT).
 
 using ExpressiveSharp.Docs.Playground.Core.Services;
 using ExpressiveSharp.Docs.Playground.Core.Services.Scenarios;
@@ -38,11 +36,10 @@ public PlaygroundLanguageServices(PlaygroundReferences references)
             throw new InvalidOperationException(
                 "PlaygroundReferences must be loaded before PlaygroundLanguageServices is constructed.");
 
-        // Append the WorkspaceShim assembly AFTER MefHostServices.DefaultAssemblies.
-        // The shim's NoOpPersistentStorageConfiguration is exported with
-        // ServiceLayer.Test which gives it MEF priority over Roslyn's broken
-        // DefaultPersistentStorageConfiguration, so the latter's cctor never
-        // runs and Process.GetCurrentProcess() (PNSE on WASM) is never called.
+        // Append WorkspaceShim AFTER DefaultAssemblies. Its NoOpPersistentStorageConfiguration
+        // exports with ServiceLayer.Test, gaining MEF priority over Roslyn's
+        // DefaultPersistentStorageConfiguration so the latter's cctor never runs
+        // (it calls Process.GetCurrentProcess() — PNSE on WASM).
         var hostServices = MefHostServices.Create(
             MefHostServices.DefaultAssemblies
                 .Append(typeof(NoOpPersistentStorageConfiguration).Assembly));
@@ -56,8 +53,7 @@ public PlaygroundLanguageServices(PlaygroundReferences references)
             assemblyName: "PlaygroundProject",
             language: LanguageNames.CSharp,
             metadataReferences: references.References,
-            // WithConcurrentBuild(false): WASM is single-threaded, parallel
-            // Roslyn compile threads deadlock or throw.
+            // WASM is single-threaded; parallel Roslyn compile threads deadlock or throw.
             compilationOptions: new CSharpCompilationOptions(OutputKind.DynamicallyLinkedLibrary)
                 .WithNullableContextOptions(NullableContextOptions.Enable)
                 .WithConcurrentBuild(false),
@@ -67,12 +63,9 @@ public PlaygroundLanguageServices(PlaygroundReferences references)
         _projectId = projectInfo.Id;
     }
 
-    /// <summary>
-    /// Forces MEF composition during page load instead of lazily on the first
-    /// keystroke. Adds a throwaway document, asks for its CompletionService
-    /// (the act of resolving it triggers MEF + the cctor moment WorkspaceShim
-    /// guards against), discards. Subsequent real completions hit warm caches.
-    /// </summary>
+    // Forces MEF composition during page load instead of lazily on the first
+    // keystroke. Resolving CompletionService triggers MEF + the cctor moment
+    // WorkspaceShim guards against; subsequent real completions hit warm caches.
     public async Task PrewarmAsync()
     {
         await _lock.WaitAsync();
@@ -117,8 +110,7 @@ public async Task RegisterEditorAsync(string modelUri, string snippetText, strin
         await _lock.WaitAsync();
         try
         {
-            // Drop any prior document under the same URI (rare — happens if
-            // an instance disposes and remounts) to avoid duplicate routing.
+            // Drop any prior document under the same URI (instance dispose + remount).
             if (_modelToDocument.TryGetValue(modelUri, out var existingId))
             {
                 _workspace.TryApplyChanges(_workspace.CurrentSolution.RemoveDocument(existingId));
@@ -137,7 +129,7 @@ public async Task RegisterEditorAsync(string modelUri, string snippetText, strin
         }
     }
 
-    // Per-keystroke (no debounce — Roslyn diffs the syntax tree, sub-ms).
+    // Called per-keystroke; no debounce — Roslyn diffs the syntax tree (sub-ms).
     public async Task UpdateEditorAsync(string modelUri, string snippetText, string? setupText, IPlaygroundScenario scenario)
     {
         var wrap = SnippetWrap.Build(scenario.WrapperTemplate, snippetText, setupText);
@@ -158,7 +150,6 @@ public async Task UpdateEditorAsync(string modelUri, string snippetText, string?
         }
     }
 
-    // Best-effort: silently no-ops if the model URI is unknown.
     public async Task UnregisterEditorAsync(string modelUri)
     {
         await _lock.WaitAsync();
@@ -236,9 +227,9 @@ public async Task UnregisterEditorAsync(string modelUri)
     }
 
     // Returns -1 if the position falls outside the snippet region.
+    // Monaco is 1-based, LinePosition is 0-based.
     private static int MonacoPositionToCaretOffset(MonacoPosition position, SourceText text, SnippetWrap wrap)
     {
-        // Monaco is 1-based, LinePosition is 0-based.
         var snippetRelative = new LinePosition(
             line: Math.Max(0, position.LineNumber - 1),
             character: Math.Max(0, position.Column - 1));

src/Docs/Playground.Wasm/Services/PlaygroundReferences.cs

@@ -1,12 +1,7 @@
-// PlaygroundReferences — fetches the reference assemblies the SnippetCompiler
-// needs into MetadataReference instances. In a Blazor WASM app every loaded
-// assembly is shipped under /_framework/<name>.dll, so we use HttpClient to
-// pull the raw bytes and feed them to MetadataReference.CreateFromImage.
-//
-// The reference set is the union of every scenario's ReferenceAssemblies,
-// loaded once at startup and cached. Adding a new scenario in Phase 2
-// automatically extends the reference set with its assemblies — no edits to
-// this file are required.
+// In Blazor WASM every loaded assembly ships under /_framework/<name>.dll, so
+// HttpClient pulls the raw bytes and feeds them to MetadataReference.CreateFromImage.
+// The reference set is the union of every scenario's ReferenceAssemblies —
+// adding a scenario to ScenarioRegistry automatically extends the set.
 
 using System.Collections.Immutable;
 using Basic.Reference.Assemblies;
@@ -36,17 +31,9 @@ public async Task LoadAsync()
 
         var builder = ImmutableArray.CreateBuilder<MetadataReference>();
 
-        // .NET 10 ref-only BCL — embedded as resources in the
-        // Basic.Reference.Assemblies.Net100 assembly. No HTTP needed; the
-        // package's own embedded resources are loaded by the normal Blazor
-        // assembly loader at startup.
+        // .NET 10 ref-only BCL — embedded resources in Basic.Reference.Assemblies.Net100.
         builder.AddRange(Net100.References.All);
 
-        // Take the union of every scenario's ReferenceAssemblies. With one
-        // scenario today this loads ExpressiveSharp + ExpressiveSharp.EntityFrameworkCore
-        // + EF Core 10 + the PlaygroundModel assembly. Future scenarios are
-        // additive: registering a Mongo scenario in ScenarioRegistry would
-        // automatically pull in MongoDB.Driver here.
         var seenNames = new HashSet<string>(StringComparer.Ordinal);
         var fetchTasks = new List<Task<MetadataReference?>>();
 
@@ -78,8 +65,7 @@ public async Task LoadAsync()
         }
         catch (HttpRequestException)
         {
-            // Missing DLL → skip; Roslyn surfaces a "missing reference" diagnostic
-            // later if the snippet actually needs the type.
+            // Missing DLL → skip; Roslyn reports "missing reference" later if needed.
             return null;
         }
     }