sourcey 3.5.10 → 3.6.1

package/README.md

@@ -12,6 +12,8 @@ No dashboard. No runtime. No API calls to render your own documentation.
 [![license](https://img.shields.io/npm/l/sourcey)](LICENSE)
 [![Go Reference](https://pkg.go.dev/badge/github.com/sourcey/sourcey/go/sourcey-godoc.svg)](https://pkg.go.dev/github.com/sourcey/sourcey/go/sourcey-godoc)
 [![Go Report Card](https://goreportcard.com/badge/github.com/sourcey/sourcey/go/sourcey-godoc)](https://goreportcard.com/report/github.com/sourcey/sourcey/go/sourcey-godoc)
+[![crates.io](https://img.shields.io/crates/v/sourcey.svg)](https://crates.io/crates/sourcey)
+[![docs.rs](https://docs.rs/sourcey/badge.svg)](https://docs.rs/sourcey)
 
 ```bash
 npx sourcey init
@@ -27,9 +29,11 @@ npx sourcey init
 - **API reference from OpenAPI**: endpoints, parameters, request/response schemas, auto-generated code samples in 10 languages (cURL, JavaScript, TypeScript, Python, Go, Ruby, Java, PHP, Rust, C#)
 - **MCP server documentation**: tools, resources, prompts rendered as browsable reference with JSON-RPC, TypeScript, and Python code samples. Color-coded method types, annotation badges, connection config cards
 - **Rich guides**: markdown pages with steps, cards, accordions, syntax-highlighted code blocks, and prose alongside your API reference
+- **MkDocs source import**: point a tab at `mkdocs.yml`; Sourcey reads `docs_dir` and `nav` so existing MkDocs markdown sites can render without hand-copying the sidebar structure
 - **Product story pages**: changelog, roadmap pages, examples, reference material, search, and portable context exports in one source-owned site
-- **C++ and Doxygen**: feed Doxygen XML output, get modern searchable API docs. No new parser, no four-tool Breathe/Exhale/Sphinx pipeline
+- **C++ and Doxygen**: feed Doxygen XML output, get modern searchable API docs with exact member search, source links, templates, qualifiers, examples, inherited members, and relationship sections. No new parser, no four-tool Breathe/Exhale/Sphinx pipeline
 - **Go and godoc**: native package documentation extracted from Go source via the toolchain. Render Go modules as Sourcey tabs, generate standalone static Go docs sites, or commit `godoc.json` snapshots for JS-only docs hosts. No Doxygen detour
+- **Rust and rustdoc**: native API documentation from nightly rustdoc JSON, with doctests as a first-class extracted view. URL-encoded parametric impl anchors for deep-link parity with doc.rust-lang.org. Snapshot mode lets CI build on stable Rust toolchains. Aggregated doctests index across the workspace
 - **Context exports**: auto-generate llms.txt and llms-full.txt alongside your HTML as alternate views of the same documentation graph
 - **TypeScript config**: `sourcey.config.ts` with `defineConfig()` autocomplete; theme, navbar, CTA buttons, footer
 - **Theme presets**: default (sidebar + TOC), minimal (single column), api-first (Stripe-style three column); colors, fonts, layout dimensions, and custom CSS on top
@@ -43,14 +47,14 @@ npx sourcey init
 
 ### Sourcey CLI
 
-The full Sourcey binary handles OpenAPI, Doxygen, godoc, MCP, and Markdown sources.
+The full Sourcey binary handles OpenAPI, MCP, Doxygen, godoc, rustdoc, MkDocs, and Markdown sources.
 
-| Path     | Command                                            | Requires          |
-|----------|----------------------------------------------------|-------------------|
-| npm      | `npm install -g sourcey`                           | Node 20+          |
-| Homebrew | `brew tap sourcey/tap && brew install sourcey`     | macOS / Linuxbrew |
-| Docker   | `docker run -v "$PWD":/docs sourcey/sourcey`       | Docker            |
-| Nix      | `nix run github:sourcey/sourcey`                   | Nix (flakes)      |
+| Path     | Command                                        | Requires          |
+| -------- | ---------------------------------------------- | ----------------- |
+| npm      | `npm install -g sourcey`                       | Node 20+          |
+| Homebrew | `brew tap sourcey/tap && brew install sourcey` | macOS / Linuxbrew |
+| Docker   | `docker run -v "$PWD":/docs sourcey/sourcey`   | Docker            |
+| Nix      | `nix run github:sourcey/sourcey`               | Nix (flakes)      |
 
 Then `sourcey init` to scaffold a new project, or `sourcey build` against an existing one. See [docs/install.md](docs/install.md) for full Docker invocations (`init` / `dev` / `build`), the `--host` flag for containerized dev, Linuxbrew notes, and Nix profile install.
 
@@ -58,10 +62,10 @@ Then `sourcey init` to scaffold a new project, or `sourcey build` against an exi
 
 For Go-only consumers without a JavaScript toolchain, `sourcey-godoc` ships as a separate native binary. It produces static Go docs sites or portable `godoc.json` snapshots.
 
-| Path     | Command |
-|----------|---------|
-| Go       | `go install github.com/sourcey/sourcey/go/sourcey-godoc/cmd/sourcey-godoc@latest` |
-| Homebrew | `brew install sourcey/tap/sourcey-godoc` |
+| Path     | Command                                                                                           |
+| -------- | ------------------------------------------------------------------------------------------------- |
+| Go       | `go install github.com/sourcey/sourcey/go/sourcey-godoc/cmd/sourcey-godoc@latest`                 |
+| Homebrew | `brew install sourcey/tap/sourcey-godoc`                                                          |
 | Scoop    | `scoop bucket add sourcey https://github.com/sourcey/scoop-bucket && scoop install sourcey-godoc` |
 
 ## Quick start
@@ -82,101 +86,29 @@ sourcey dev
 Create `sourcey.config.ts` in your project root:
 
 ```typescript
-import { defineConfig } from "sourcey";
+import { defineConfig, openapi } from "sourcey";
 
 export default defineConfig({
   name: "My API",
-  theme: {
-    preset: "default",  // "default" | "minimal" | "api-first"
-    colors: {
-      primary: "#6366F1",
-      light: "#818CF8",
-      dark: "#4F46E5",
-    },
-  },
-  logo: "./logo.png",
   navigation: {
-    tabs: [
-      {
-        tab: "Documentation",
-        groups: [
-          {
-            group: "Getting Started",
-            pages: ["introduction", "quickstart", "authentication"],
-          },
-        ],
-      },
-      {
-        tab: "API Reference",
-        openapi: "./openapi.yaml",
-      },
-      {
-        tab: "MCP Server",
-        mcp: "./mcp.json",
-      },
-    ],
-  },
-  navbar: {
-    links: [{ type: "github", href: "https://github.com/you/repo" }],
-    primary: { type: "button", label: "Dashboard", href: "https://app.example.com" },
-  },
-  footer: {
-    socials: { github: "https://github.com/you/repo" },
+    tabs: [{ tab: "API Reference", source: openapi("./openapi.yaml") }],
   },
 });
 ```
 
-Each tab is an `openapi` spec, an `mcp` snapshot, a `doxygen` directory, a `godoc` Go module, or `groups` of markdown pages. Pages are referenced by slug (e.g. `"quickstart"` resolves to `quickstart.md`).
+Each tab has one `source`, usually created with `markdown()`, `mkdocs()`, `openapi()`, `mcp()`, `doxygen()`, `godoc()`, or `rustdoc()`. Pages are referenced by slug (e.g. `"quickstart"` resolves to `quickstart.md`). See [docs/configuration.md](docs/configuration.md) for theme, navbar, footer, logo, and full tab options.
 
 ### Go documentation (godoc)
 
-Add a Go module as a tab and Sourcey extracts package docs natively (no Doxygen pipeline):
-
-```typescript
-{
-  tab: "Go API",
-  godoc: {
-    module: ".",
-    packages: ["./internal/core/...", "./cmd/..."],
-    // sourceBasePath: "go/my-module" // repo-relative prefix for source links when module is not at repo root
-    // mode: "auto"   // default; live when Go is available, snapshot otherwise
-    // includeTests: true       // examples from *_test.go (default)
-    // includeUnexported: false // hide unexported symbols (default)
-  },
-}
-```
-
-The string shorthand is `godoc: "."` and expands to `{ module: ".", packages: ["./..."], mode: "auto", includeTests: true }`.
-
-`editBasePath` remains the global base for Markdown "Edit this page" links.
-Use `godoc.sourceBasePath` only when Go source files live under a different
-repository prefix than the docs source.
+Render Go package docs as a tab inside your Sourcey site, branded and styled with the rest of your documentation. Native toolchain extraction (`go list` + `go/parser` + `go/doc`) feeds the same renderer as your OpenAPI, MCP, and Markdown tabs, so signatures, examples from `*_test.go`, and source links sit alongside your guides instead of bouncing readers to pkg.go.dev.
 
-Live mode invokes `go list` + `go/parser` + `go/doc` against the host Go toolchain. To pin a build environment for reproducibility, set `goEnv: { GOOS, GOARCH, tags }`.
-
-Snapshot mode reads a committed `godoc.json` and needs no Go on the build host. Generate it with:
-
-```bash
-sourcey godoc --module . --packages './...' --out docs/godoc.json
-```
-
-then point the tab at it:
+**[Live: scafld's Go API reference →](https://0state.com/scafld/docs/go-api)**
 
 ```typescript
-{
-  tab: "Go API",
-  godoc: { mode: "snapshot", snapshot: "./docs/godoc.json" },
-}
+{ tab: "Go API", source: godoc(".") }
 ```
 
-The extractor is also a standalone Go CLI for projects that want a native Go
-docs generator without installing the full Sourcey npm package:
-
-```bash
-go install github.com/sourcey/sourcey/go/sourcey-godoc/cmd/sourcey-godoc@latest
-sourcey-godoc generate --module . --packages './...' --out site
-sourcey-godoc snapshot --module . --packages './...' --out docs/godoc.json
-```
+The shorthand expands to `{ module: ".", packages: ["./..."], mode: "auto", includeTests: true }`. Live mode uses the host Go toolchain; snapshot mode reads a committed `godoc.json` and needs no Go on the build host. See [docs/configuration.md](docs/configuration.md) for `packages`, `mode`, `goEnv`, `sourceBasePath`, and `includeUnexported`.
 
 ### Markdown components
 
@@ -226,12 +158,7 @@ sourcey godoc --out godoc.json    Snapshot a Go module's docs to JSON
 sourcey-godoc generate --out site Standalone Go CLI for static godoc sites
 ```
 
-| Command | Flag | Description |
-| --- | --- | --- |
-| `build` | `--output, -o` | Output directory (default: `dist`) |
-| `build` | `--embed, -e` | Embeddable output (no html/body wrapper) |
-| `build` | `--quiet, -q` | Suppress output |
-| `dev` | `--port, -p` | Dev server port (default: `4400`) |
+Run `sourcey <command> --help` for flags.
 
 ## Development
 

package/dist/adapters/index.d.ts

@@ -0,0 +1,12 @@
+import type { DoxygenSourceOptions, GodocSourceOptions, MarkdownSourceOptions, McpSourceOptions, MkDocsSourceOptions, OpenApiSourceOptions, RustdocSourceOptions, SourceAdapter } from "./types.js";
+import { assertLocalPath } from "./shared.js";
+export declare function openapi(specOrOptions: string | OpenApiSourceOptions): SourceAdapter;
+export declare function mcp(specOrOptions: string | McpSourceOptions): SourceAdapter;
+export declare function markdown(options: MarkdownSourceOptions): SourceAdapter;
+export declare function mkdocs(configOrOptions: string | MkDocsSourceOptions): SourceAdapter;
+export declare function doxygen(options: DoxygenSourceOptions): SourceAdapter;
+export declare function godoc(configOrPath: GodocSourceOptions): SourceAdapter;
+export declare function rustdoc(configOrPath: RustdocSourceOptions): SourceAdapter;
+export { assertLocalPath };
+export type { DoxygenSourceOptions, GodocSourceOptions, MarkdownSourceOptions, McpSourceOptions, MkDocsSourceOptions, OpenApiSourceOptions, PageMarkdownOptions, ResolvedTabSource, RustdocSourceOptions, SourceAdapter, SourceAdapterContext, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EACpB,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,EAChB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,aAAa,EACd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAuC,MAAM,aAAa,CAAC;AAGnF,wBAAgB,OAAO,CAAC,aAAa,EAAE,MAAM,GAAG,oBAAoB,GAAG,aAAa,CAanF;AAED,wBAAgB,GAAG,CAAC,aAAa,EAAE,MAAM,GAAG,gBAAgB,GAAG,aAAa,CAa3E;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,qBAAqB,GAAG,aAAa,CAWtE;AAED,wBAAgB,MAAM,CAAC,eAAe,EAAE,MAAM,GAAG,mBAAmB,GAAG,aAAa,CAInF;AAED,wBAAgB,OAAO,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAsBpE;AAED,wBAAgB,KAAK,CAAC,YAAY,EAAE,kBAAkB,GAAG,aAAa,CA6BrE;AAED,wBAAgB,OAAO,CAAC,YAAY,EAAE,oBAAoB,GAAG,aAAa,CAmCzE;AAMD,OAAO,EAAE,eAAe,EAAE,CAAC;AAC3B,YAAY,EACV,oBAAoB,EACpB,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,EAChB,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,iBAAiB,EACjB,oBAAoB,EACpB,aAAa,EACb,oBAAoB,GACrB,MAAM,YAAY,CAAC"}

package/dist/adapters/index.js

@@ -0,0 +1,130 @@
+import { assertLocalPath, resolveMarkdownGroups, toWatchPaths } from "./shared.js";
+import { mkdocs as mkdocsAdapter } from "./mkdocs.js";
+export function openapi(specOrOptions) {
+    const spec = typeof specOrOptions === "string" ? specOrOptions : specOrOptions.spec;
+    return {
+        name: "openapi",
+        async resolve(ctx) {
+            if (ctx.isUrl(spec)) {
+                return { kind: "openapi", spec };
+            }
+            const absPath = ctx.resolvePath(spec);
+            await ctx.assertExists(absPath, `OpenAPI spec "${spec}" in tab "${ctx.tabName}"`);
+            return { kind: "openapi", spec: absPath, watchPaths: [absPath] };
+        },
+    };
+}
+export function mcp(specOrOptions) {
+    const spec = typeof specOrOptions === "string" ? specOrOptions : specOrOptions.spec;
+    return {
+        name: "mcp",
+        async resolve(ctx) {
+            if (ctx.isUrl(spec)) {
+                return { kind: "mcp", spec };
+            }
+            const absPath = ctx.resolvePath(spec);
+            await ctx.assertExists(absPath, `MCP spec "${spec}" in tab "${ctx.tabName}"`);
+            return { kind: "mcp", spec: absPath, watchPaths: [absPath] };
+        },
+    };
+}
+export function markdown(options) {
+    return {
+        name: "markdown",
+        async resolve(ctx) {
+            return {
+                kind: "markdown",
+                adapter: "markdown",
+                groups: await resolveMarkdownGroups(options.groups, ctx.tabName, ctx.configDir),
+            };
+        },
+    };
+}
+export function mkdocs(configOrOptions) {
+    const options = typeof configOrOptions === "string" ? { config: configOrOptions } : configOrOptions;
+    return mkdocsAdapter(options);
+}
+export function doxygen(options) {
+    return {
+        name: "doxygen",
+        async resolve(ctx) {
+            const absXml = assertLocalPath(ctx, options.xml, "Doxygen XML directory");
+            await ctx.assertExists(absXml, `Doxygen XML directory "${options.xml}" in tab "${ctx.tabName}"`);
+            return {
+                kind: "doxygen",
+                config: {
+                    xml: absXml,
+                    language: options.language ?? "cpp",
+                    groups: options.groups ?? false,
+                    index: options.index === false ? "none" : (options.index ?? "auto"),
+                    sourceUrl: options.sourceUrl,
+                },
+                watchPaths: [absXml],
+            };
+        },
+    };
+}
+export function godoc(configOrPath) {
+    return {
+        name: "godoc",
+        async resolve(ctx) {
+            const cfg = typeof configOrPath === "string" ? { module: configOrPath } : configOrPath;
+            const moduleAbs = assertLocalPath(ctx, cfg.module ?? ".", "Go module directory");
+            await ctx.assertExists(moduleAbs, `Go module directory "${cfg.module ?? "."}" in tab "${ctx.tabName}"`);
+            const snapshotAbs = cfg.snapshot ? ctx.resolvePath(cfg.snapshot) : undefined;
+            return {
+                kind: "godoc",
+                config: {
+                    module: moduleAbs,
+                    packages: cfg.packages?.length ? cfg.packages : ["./..."],
+                    snapshot: snapshotAbs,
+                    mode: cfg.mode ?? "auto",
+                    includeTests: cfg.includeTests ?? true,
+                    includeUnexported: cfg.includeUnexported ?? false,
+                    hideUndocumented: cfg.hideUndocumented ?? false,
+                    exclude: cfg.exclude ?? [],
+                    goEnv: cfg.goEnv,
+                    sourceBasePath: trimSlashes(cfg.sourceBasePath ?? ""),
+                },
+                watchPaths: toWatchPaths([snapshotAbs]),
+            };
+        },
+    };
+}
+export function rustdoc(configOrPath) {
+    return {
+        name: "rustdoc",
+        async resolve(ctx) {
+            const cfg = typeof configOrPath === "string" ? { manifest: configOrPath } : configOrPath;
+            const manifestAbs = assertLocalPath(ctx, cfg.manifest ?? ".", "Cargo manifest");
+            await ctx.assertExists(manifestAbs, `Cargo manifest "${cfg.manifest ?? "."}" in tab "${ctx.tabName}"`);
+            const snapshotAbs = cfg.snapshot ? ctx.resolvePath(cfg.snapshot) : undefined;
+            const features = {
+                default: cfg.features?.default ?? true,
+                list: cfg.features?.list ?? [],
+                all: cfg.features?.all ?? false,
+            };
+            return {
+                kind: "rustdoc",
+                config: {
+                    manifest: manifestAbs,
+                    crates: cfg.crates?.length ? cfg.crates : [],
+                    snapshot: snapshotAbs,
+                    mode: cfg.mode ?? "auto",
+                    features,
+                    includePrivate: cfg.includePrivate ?? false,
+                    includeHidden: cfg.includeHidden ?? false,
+                    target: cfg.target,
+                    toolchain: cfg.toolchain ?? "nightly",
+                    sourceBasePath: trimSlashes(cfg.sourceBasePath ?? ""),
+                    doctestsIndex: cfg.doctestsIndex ?? true,
+                },
+                watchPaths: toWatchPaths([snapshotAbs]),
+            };
+        },
+    };
+}
+function trimSlashes(value) {
+    return value.replace(/^\/+|\/+$/g, "");
+}
+export { assertLocalPath };

package/dist/adapters/mkdocs.d.ts

@@ -0,0 +1,5 @@
+import type { MarkdownPreprocessor } from "../core/markdown-loader.js";
+import type { MkDocsSourceOptions, SourceAdapter } from "./types.js";
+export declare function mkdocs(options: MkDocsSourceOptions): SourceAdapter;
+export declare const preprocessMkDocsMarkdown: MarkdownPreprocessor;
+//# sourceMappingURL=mkdocs.d.ts.map

package/dist/adapters/mkdocs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mkdocs.d.ts","sourceRoot":"","sources":["../../src/adapters/mkdocs.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAcrE,wBAAgB,MAAM,CAAC,OAAO,EAAE,mBAAmB,GAAG,aAAa,CAoBlE;AAiLD,eAAO,MAAM,wBAAwB,EAAE,oBAWtC,CAAC"}