starlight-fsharp-oracle 0.1.0

package/oracle-bin/Oracle.xml

@@ -0,0 +1,111 @@
+<?xml version="1.0" encoding="utf-8"?>
+<doc>
+<assembly><name>Oracle</name></assembly>
+<members>
+<member name="M:Oracle.XmlDoc.moduleDocOf(Microsoft.FSharp.Collections.FSharpMap{System.String,System.String},System.String)">
+<summary>
+ Look up just the summary for a module-level signature.
+ Used for Module.XmlDoc which is stored as a plain string in the IR.
+</summary>
+</member>
+<member name="M:Oracle.XmlDoc.xmlDocOf(Microsoft.FSharp.Collections.FSharpMap{System.String,System.String},System.String)">
+<summary>
+ Look up and parse the XML doc for a given member signature.
+ Returns an empty XmlDoc when the signature is not found in the map.
+</summary>
+</member>
+<member name="M:Oracle.XmlDoc.loadXmlDocFile(System.String)">
+<summary>
+ Load the XML documentation file that lives next to a compiled DLL and
+ return a lookup map from the standard XML-doc member ID (e.g.
+ &quot;M:My.Namespace.func(System.Int32)&quot;) to the inner XML content of that
+ &lt;member&gt; element.
+</summary>
+</member>
+<member name="M:Oracle.XmlDoc.fixXmlAttributeChars(System.String)">
+<summary>
+ Escape `&lt;` and `&gt;` characters that appear inside XML attribute values.
+ The F# compiler sometimes generates invalid XML for anonymous record
+ type signatures (e.g. `name=&quot;M:Foo(&lt;&gt;f__AnonymousType...)`).
+</summary>
+</member>
+<member name="M:Oracle.XmlDoc.parseXmlContent(System.String)">
+<summary>
+ Parse the inner XML content of a &lt;member&gt; element into the structured
+ XmlDoc IR type, with all inline tags converted to Markdown.
+</summary>
+</member>
+<member name="M:FSharp.Oracle.Helpers.resolveCref(Microsoft.FSharp.Core.FSharpFunc{System.String,System.String},System.String)">
+<summary>
+ Resolves XML-doc &lt;see cref=&quot;...&quot;/&gt; strings to page URLs.
+ cref format: T:Namespace.Type or M:Namespace.Type.Member(...)
+</summary>
+</member>
+<member name="P:FSharp.Oracle.Helpers.postfixTypeNames">
+<summary>
+ Full names for types that conventionally use postfix syntax in F#.
+</summary>
+</member>
+<member name="P:FSharp.Oracle.Helpers.postfixTypeDisplayNames">
+<summary>
+ Display names for types that conventionally use postfix syntax in F#.
+</summary>
+</member>
+<member name="M:FSharp.Oracle.Helpers.isSrtp(FSharp.Compiler.Symbols.FSharpGenericParameter)">
+<summary>
+ True for SRTP parameters (have member/static-member constraints).
+</summary>
+</member>
+<member name="M:FSharp.Oracle.Helpers.safeFullName(FSharp.Compiler.Symbols.FSharpEntity)">
+<summary>
+ Compute a safe FullName for any entity.
+ Type abbreviations for primitives (e.g. `type Meters = float`) throw on FullName;
+ fall back to constructing it from Namespace + DisplayName.
+</summary>
+</member>
+<member name="M:FSharp.Oracle.Helpers.tryGetFullName(FSharp.Compiler.Symbols.FSharpEntity)">
+<summary>
+ Try to get FullName from a FSharpEntity; returns None for primitives
+ like &apos;string&apos;, &apos;int&apos; that are F# type abbreviations with no qualified name.
+</summary>
+</member>
+<member name="M:FSharp.Oracle.Helpers.namespaceOf(System.String)">
+<summary>
+ Returns everything before the last dot, e.g. &quot;A.B.C&quot; → &quot;A.B&quot;.
+ Returns &quot;&quot; for unqualified names.
+</summary>
+</member>
+<member name="M:FSharp.Oracle.SignatureRendering.stripGenericParamBrackets(Microsoft.FSharp.Core.FSharpOption{FSharp.Oracle.Schema.TextNode})">
+<summary>
+ Strip `&lt;`, `&gt;` and the leading type variable from a generic-parameter list,
+ returning only the constraint clause (e.g. ` when &apos;T : comparison`).
+ Used to append constraints after a value/member signature.
+</summary>
+</member>
+<member name="M:FSharp.Oracle.SignatureRendering.renderGenericParams(Microsoft.FSharp.Core.FSharpFunc{System.String,System.String},System.Collections.Generic.IEnumerable{FSharp.Compiler.Symbols.FSharpGenericParameter})">
+<summary>
+ Render the generic-parameter list for a function or member, e.g.
+ `&lt;&apos;T when &apos;T : comparison&gt;` or `&lt;^T when ^T : (static member (+) : ^T * ^T -&gt; ^T)&gt;`.
+ Returns `None` when there are no parameters.
+</summary>
+</member>
+<member name="M:FSharp.Oracle.SignatureRendering.renderConstraint(Microsoft.FSharp.Core.FSharpFunc{System.String,System.String},FSharp.Compiler.Symbols.FSharpGenericParameter,FSharp.Compiler.Symbols.FSharpGenericParameterConstraint)">
+<summary>
+ Render a single generic parameter constraint as a TextNode list.
+</summary>
+</member>
+<member name="M:FSharp.Oracle.MemberExtractor.buildMemberDeclaration(FSharp.Oracle.Schema.MemberKind,System.String,System.Boolean,System.Boolean,Microsoft.FSharp.Collections.FSharpList{Microsoft.FSharp.Collections.FSharpList{FSharp.Oracle.Schema.Parameter}},FSharp.Oracle.Schema.TextNode,FSharp.Oracle.Schema.TextNode)">
+<summary>
+ Builds the signature TextNode for the per-member DocEntry slot (no anchors, no indentation).
+ This is the pre-computed Declaration stored on Member.
+</summary>
+</member>
+<member name="M:FSharp.Oracle.Extractor.extractAssembly(FSharp.Compiler.CodeAnalysis.FSharpChecker,System.String[],System.String,System.String)">
+<summary>
+ Extract the JSON IR for a single compiled .dll + optional .xml doc file.
+ The checker must have already been created with [allDllPaths] as references
+ so cross-assembly resolution works.
+</summary>
+</member>
+</members>
+</doc>

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "starlight-fsharp-oracle",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": "./dist/Plugin.js",
+    "./components/DocEntry.astro": "./packages/Starlight.FSharp.Oracle/components/DocEntry.astro",
+    "./components/FSharpDocPage.astro": "./packages/Starlight.FSharp.Oracle/components/FSharpDocPage.astro",
+    "./layouts/FSharpDocLayout.astro": "./packages/Starlight.FSharp.Oracle/layouts/FSharpDocLayout.astro"
+  },
+  "files": [
+    "dist/**/*",
+    "oracle-bin/",
+    "packages/FSharp.Oracle/**/*.fs",
+    "!packages/FSharp.Oracle/obj",
+    "packages/FSharp.Oracle/*.fsproj",
+    "packages/FSharp.Oracle.Schema/**/*.fs",
+    "!packages/FSharp.Oracle.Schema/obj",
+    "packages/FSharp.Oracle.Schema/*.fsproj",
+    "packages/Starlight.FSharp.Oracle/components/",
+    "packages/Starlight.FSharp.Oracle/layouts/",
+    "Directory.Build.props",
+    "Directory.Packages.props"
+  ],
+  "scripts": {
+    "postinstall": "dotnet publish packages/FSharp.Oracle/FSharp.Oracle.fsproj -c Release --nologo -o oracle-bin"
+  },
+  "peerDependencies": {
+    "@astrojs/starlight": ">= 0.38.0",
+    "astro-expressive-code": ">= 0.38.0"
+  },
+  "devDependencies": {
+    "@hideoo/tsconfig": "^2.0.3",
+    "@types/node": "^25.6.0",
+    "astro-expressive-code": "^0.41.7",
+    "typescript": "^5.8.0"
+  }
+}

package/packages/FSharp.Oracle/Extractor/Assembly.fs

@@ -0,0 +1,160 @@
+module FSharp.Oracle.Extractor
+
+open FSharp.Compiler.CodeAnalysis
+open FSharp.Compiler.Symbols
+open FSharp.Oracle.Schema
+open Oracle.XmlDoc
+open FSharp.Oracle.Helpers
+open FSharp.Oracle.EntityExtractor
+open FSharp.Oracle.ModuleExtractor
+
+// ---------------------------------------------------------------------------
+// Public entry point
+// ---------------------------------------------------------------------------
+
+/// Extract the JSON IR for a single compiled .dll + optional .xml doc file.
+/// The checker must have already been created with [allDllPaths] as references
+/// so cross-assembly resolution works.
+let extractAssembly
+    (checker: FSharpChecker)
+    (allDllPaths: string array)
+    (outputBase: string)
+    (dllPath: string)
+    : Assembly
+    =
+    let toSlug (name: string) =
+        let sanitized = name.ToLowerInvariant().Replace(".", "-")
+        // Strip F# generic arity suffix (e.g. Tree`1 -> tree)
+        System.Text.RegularExpressions.Regex.Replace(sanitized, @"`\d+$", "")
+
+    let toUrl (fullName: string) = $"/{outputBase}/{toSlug fullName}"
+
+    let baseOptions, _ =
+        checker.GetProjectOptionsFromScript(
+            "dummy.fsx",
+            FSharp.Compiler.Text.SourceText.ofString ""
+        )
+        |> Async.RunSynchronously
+
+    // Reference every DLL so FCS can resolve cross-assembly dependencies.
+    let projectOptions =
+        { baseOptions with
+            OtherOptions =
+                [|
+                    yield! baseOptions.OtherOptions
+                    for path in allDllPaths do
+                        $"-r:{path}"
+                |]
+        }
+
+    // Load the assembly via FCS reflection
+    let fsharpAssembly =
+        checker.ParseAndCheckProject(projectOptions)
+        |> Async.RunSynchronously
+        // Walk the resolved assemblies to find the target dll
+        |> fun results ->
+            let targetName = System.IO.Path.GetFileNameWithoutExtension(dllPath)
+
+            results.ProjectContext.GetReferencedAssemblies()
+            |> List.tryFind (fun a -> a.SimpleName = targetName)
+
+    match fsharpAssembly with
+    | None -> failwithf "Could not load assembly: %s" dllPath
+    | Some asm ->
+        let docs = loadXmlDocFile dllPath
+
+        // Recursively collect a module and all its nested sub-modules as
+        // separate pages (each sub-module becomes its own page).
+        let rec collectModulePages (entity: FSharpEntity) : Module list =
+            let thisPage = extractModule toUrl docs entity
+
+            let subPages =
+                entity.NestedEntities
+                |> Seq.filter (fun e -> e.IsFSharpModule)
+                |> Seq.collect collectModulePages
+                |> Seq.toList
+
+            thisPage :: subPages
+
+        // All pages that come from module entities (including sub-modules).
+        let modulePages =
+            asm.Contents.Entities
+            |> Seq.filter (fun e -> e.IsFSharpModule)
+            |> Seq.collect collectModulePages
+            |> Seq.toList
+
+        // Bare types at the assembly root that live in a namespace but are not
+        // inside any module (e.g. record/union types declared directly in a
+        // namespace declaration).  Group them by their namespace and emit one
+        // synthetic module page per namespace.
+        let syntheticPages =
+            asm.Contents.Entities
+            |> Seq.filter (fun e ->
+                not e.IsFSharpModule && not e.IsNamespace && not e.IsArrayType && not e.IsByRef
+            )
+            |> Seq.groupBy (fun e -> namespaceOf (safeFullName e))
+            |> Seq.map (fun (ns, entities) ->
+                {
+                    Name = "global"
+                    FullName = ns + ".global"
+                    Namespace = ns
+                    XmlDoc = None
+                    Entities = entities |> Seq.map (extractEntity toUrl docs) |> Seq.toList
+                    Functions = []
+                    Values = []
+                    IsSynthetic = true
+                    ObsoleteInfo = ObsoleteInfo.Active
+                }
+            )
+            |> Seq.toList
+
+        let rec collectFcsNamespaces (entity: FSharpEntity) : string list =
+            if entity.IsNamespace then
+                let nested = entity.NestedEntities |> Seq.collect collectFcsNamespaces |> Seq.toList
+                entity.FullName :: nested
+            else
+                []
+
+        let allModules = modulePages @ syntheticPages
+
+        let namespaceNames =
+            [
+                yield! asm.Contents.Entities |> Seq.collect collectFcsNamespaces
+
+                yield!
+                    allModules
+                    |> List.map (fun m -> m.Namespace)
+                    |> List.filter (fun ns -> ns <> "")
+            ]
+            |> List.distinct
+            |> List.sort
+
+        let namespaces =
+            [
+                // "global" if any module has no namespace
+                if allModules |> List.exists (fun m -> m.Namespace = "") then
+                    {
+                        Name = "global"
+                        FullName = ""
+                    }
+
+                for ns in namespaceNames do
+                    let name =
+                        let lastDot = ns.LastIndexOf('.')
+
+                        if lastDot < 0 then
+                            ns
+                        else
+                            ns.[lastDot + 1 ..]
+
+                    {
+                        Name = name
+                        FullName = ns
+                    }
+            ]
+
+        {
+            Name = asm.SimpleName
+            Namespaces = namespaces
+            Modules = allModules
+        }