Attempting to fix typescript reference generator

Author: caesay

.github/workflows/generate.yml

@@ -22,7 +22,7 @@ jobs:
       - name: Set up .NET
         uses: actions/setup-dotnet@v5
         with:
-          dotnet-version: '9.x'
+          dotnet-version: '10.x'
       - name: Generate CLI Reference
         working-directory: generator
         run: dotnet run -- cli refout
@@ -39,10 +39,10 @@ jobs:
       - name: Set up .NET
         uses: actions/setup-dotnet@v5
         with:
-          dotnet-version: '9.x'
+          dotnet-version: '10.x'
       - name: Generate
         working-directory: generator
-        run: dotnet run
+        run: dotnet run -- --strict
       - uses: caesay/wait-artifact-action@master
         with:
           token: ${{ secrets.GITHUB_TOKEN }}

generator/Languages/TypeScript/TypeScriptExtractor.cs

@@ -54,11 +54,31 @@ internal static class TypeScriptExtractor
         // Install typedoc + typescript locally in the extracted package.
         await Util.RunProcessAsync("npm", new[] { "install", "--no-audit", "--no-fund", "typedoc", "typescript" }, packageDir);
 
+        // TypeScript discovers a tsconfig.json by walking up the directory tree from the entry
+        // point. The work dir lives inside this docs repo, whose root tsconfig.json extends
+        // "@docusaurus/tsconfig" — not installed here — so the walk-up resolves to it and fails
+        // with TS6053, killing the run. Write a self-contained tsconfig next to the entry point
+        // and point typedoc at it so the search never escapes the package.
+        var tsconfig = Path.Combine(packageDir, "tsconfig.typedoc.json");
+        await File.WriteAllTextAsync(tsconfig, """
+        {
+          "compilerOptions": {
+            "target": "ESNext",
+            "module": "ESNext",
+            "moduleResolution": "node",
+            "skipLibCheck": true,
+            "noEmit": true
+          },
+          "include": ["**/*.d.ts"]
+        }
+        """);
+
         var jsonOut = Path.Combine(workDir, "typedoc.json");
         var result = await Util.RunCaptureAsync("npx", new[]
         {
             "typedoc",
             "--json", jsonOut,
+            "--tsconfig", tsconfig,
             "--entryPoints", entry,
             "--entryPointStrategy", "expand",
             "--skipErrorChecking",

generator/Program.cs

@@ -21,6 +21,16 @@ static async Task Main(string[] args)
         string docRootDir = Path.GetFullPath(Path.Combine(scriptsDir, ".."));
         string ReferenceDir(string lang) => Path.Combine(docRootDir, "docs", "reference", lang);
 
+        // Strict mode: a language that fails to generate is a HARD ERROR (non-zero exit) instead
+        // of silently keeping the previously-committed docs. Auto-on in CI (GitHub sets CI=true)
+        // so a broken extractor fails the workflow rather than shipping stale reference pages;
+        // off locally so a dev missing Docker/npm/python can still regenerate the subset they can.
+        // Pass --strict to force it on anywhere.
+        bool strict = args.Contains("--strict")
+            || !string.IsNullOrEmpty(Environment.GetEnvironmentVariable("CI"));
+        args = args.Where(a => a != "--strict").ToArray();
+        var failures = new List<string>();
+
         // CLI-only mode (used by the per-OS CI matrix to capture native help text).
         if (args.Length == 2 && args[0] == "cli") {
             Console.WriteLine("Generating CLI Reference Only...");
@@ -51,23 +61,23 @@ static async Task Main(string[] args)
 
         // Unified pipeline: extractor → adapter → ApiModel → MarkdownWriter, one per language.
         if (Enabled("cs"))
-            await RunLanguageAsync("C#", ReferenceDir("cs"),
+            await RunLanguageAsync("C#", ReferenceDir("cs"), failures, strict,
                 async () => { var e = await CSharpExtractor.ExtractAsync(); return e == null ? null : CSharpAdapter.Build(e); });
 
         if (Enabled("js"))
-            await RunLanguageAsync("JavaScript", ReferenceDir("js"),
+            await RunLanguageAsync("JavaScript", ReferenceDir("js"), failures, strict,
                 async () => { var e = await TypeScriptExtractor.ExtractAsync(); return e == null ? null : TypeScriptAdapter.Build(e); });
 
         if (Enabled("cpp"))
         {
             CppExtractResult? cppExtract = null;
-            await RunLanguageAsync("C++", ReferenceDir("cpp"),
+            await RunLanguageAsync("C++", ReferenceDir("cpp"), failures, strict,
                 async () => { cppExtract = await CppExtractor.ExtractAsync(); return cppExtract == null ? null : CppAdapter.Build(cppExtract); },
                 afterWrite: dir => CppAdapter.WriteCApiPage(cppExtract!, dir));
         }
 
         if (Enabled("py"))
-            await RunLanguageAsync("Python", ReferenceDir("py"),
+            await RunLanguageAsync("Python", ReferenceDir("py"), failures, strict,
                 async () => { var e = await PythonExtractor.ExtractAsync(); return e == null ? null : PythonAdapter.Build(e); });
 
         Console.WriteLine("Updating CLI Reference...");
@@ -77,34 +87,57 @@ await RunLanguageAsync("Python", ReferenceDir("py"),
             Console.WriteLine($"  CLI reference failed: {ex.Message}");
         }
 
+        // In strict mode (CI), surface every failed language at once and exit non-zero so the
+        // workflow fails loudly instead of committing stale docs for the broken language(s).
+        if (failures.Count > 0)
+        {
+            Console.Error.WriteLine($"\n{failures.Count} reference(s) failed (strict mode):");
+            foreach (var f in failures)
+                Console.Error.WriteLine($"  - {f}");
+            Environment.Exit(1);
+        }
+
         Console.WriteLine("Done!");
     }
 
     /// <summary>
-    /// Run one language pipeline. On any failure (tool missing, network down, empty model)
-    /// the existing committed docs are left untouched so the site keeps building.
+    /// Run one language pipeline. On any failure (tool missing, network down, empty model) the
+    /// existing committed docs are left untouched so the site keeps building — UNLESS
+    /// <paramref name="strict"/> is set, in which case the failure is recorded in
+    /// <paramref name="failures"/> and turned into a non-zero exit by the caller (CI behaviour).
     /// </summary>
-    static async Task RunLanguageAsync(string display, string outputDir, Func<Task<ApiModel?>> build, Action<string>? afterWrite = null)
+    static async Task RunLanguageAsync(string display, string outputDir, List<string> failures, bool strict, Func<Task<ApiModel?>> build, Action<string>? afterWrite = null)
     {
+        // In strict mode, "keep existing docs" is itself the failure we want to catch.
+        string Skip(string reason)
+        {
+            if (strict) {
+                Console.WriteLine($"  {display}: {reason} — FAILING (strict mode).");
+                failures.Add($"{display}: {reason}");
+            } else {
+                Console.WriteLine($"  {display}: {reason} — keeping existing docs.");
+            }
+            return reason;
+        }
+
         Console.WriteLine($"Updating {display} Reference...");
         try {
             var model = await build();
             if (model == null) {
-                Console.WriteLine($"  {display}: extractor unavailable — keeping existing docs.");
+                Skip("extractor produced no model");
                 return;
             }
             var typeCount = model.Namespaces.Sum(n => n.Types.Count);
             if (typeCount == 0) {
-                Console.WriteLine($"  {display}: model has no types — keeping existing docs.");
+                Skip("model has no types");
                 return;
             }
             Util.EnsureEmptyDirectory(outputDir);
             MarkdownWriter.Write(model, outputDir);
             afterWrite?.Invoke(outputDir);
             Console.WriteLine($"  {display}: wrote {typeCount} type page(s) to {outputDir}.");
         } catch (Exception ex) {
-            Console.WriteLine($"  {display} reference failed: {ex.Message}");
-            Console.WriteLine($"  Keeping existing {display} docs.");
+            Skip($"reference failed: {ex.Message}");
         }
     }