nimbus-docs 0.1.10 → 0.1.11

package/dist/index.js

@@ -1,4 +1,4 @@
-import { o as validateLintOptions, r as suggest, t as IMPLEMENTED_CODES } from "./rules-DDDvKkyJ.js";
+import { o as validateLintOptions, r as suggest, t as IMPLEMENTED_CODES } from "./rules-CzB-afEb.js";
 import { i as toRouteKey, n as isAbsoluteUrl, r as toBrowserHref, t as withStrictKeys } from "./strict-keys-fbKKxxKL.js";
 import { createRequire } from "node:module";
 import { execFile } from "node:child_process";
@@ -118,28 +118,16 @@ function slug(value, maintainCase) {
 * Mirror of Astro's content-layer slug normalization, used by every
 * framework URL builder that derives a URL from an `entry.id`.
 *
-* Astro's `glob` content loader (used by Nimbus's `docsCollection` /
-* `partialsCollection` factories) runs each path segment through
+* Astro's `glob` content loader runs each path segment through
 * `github-slugger.slug()` and strips a trailing `/index`. That output is
-* what `entry.id` becomes inside `getCollection`, and it's what `params.slug`
-* substitutes into `[...slug].astro` routes. Anything that constructs a
-* URL from the raw filesystem path *must* apply the same normalization or
-* the URL won't match what Astro actually serves.
-*
-* Why mirror instead of asking Astro: framework URL builders run at page
-* render time (sidebar hrefs) and during the integration's
-* `astro:config:setup` (sitemap, llms.txt). At neither point do we have a
-* clean way to read Astro's resolved routes. The honest architectural fix
-* is to refactor those builders to consume the route manifest at
-* `astro:routes:resolved` (sitemap/llms) or via a build-emitted lookup
-* table (sidebar). Until that work lands, this helper keeps the URLs
-* correct.
-*
-* Mirror caveat: this matches `github-slugger.slug()` and the trailing-
-* /index strip — the documented public-library behaviors Astro inherits
-* — not Astro's private routing internals. If a user supplies a custom
-* `generateId` to the content loader, or a `data.slug` override in
-* frontmatter, this helper doesn't see it. Both are uncommon.
+* what `entry.id` becomes and what `params.slug` substitutes into
+* `[...slug].astro` routes, so anything building a URL from the raw
+* filesystem path must apply the same normalization to match what Astro
+* serves.
+*
+* Caveat: this matches `github-slugger.slug()` and the trailing-/index
+* strip, not a custom loader `generateId` or a `data.slug` frontmatter
+* override — neither of which this helper sees.
 */
 /** Canonicalize one entry id the way Astro's content layer does. */
 function canonicalSlug(entryId) {
@@ -489,12 +477,9 @@ function hasActivePage(item, currentPath) {
 * URL prefix* — e.g. `Components` mounted at `/components/` —
 * rather than a sub-directory of the primary docs collection.
 *
-* Why this matters: under the previous unconditional behavior, every
-* top-level group in the sidebar (including `wip/`, `lab/`, and other
-* docs-collection subdirectories) was promoted to a header tab. The
-* header rail is meant for "other collections" navigation, not for
-* sub-sections of the default collection — those belong in the
-* sidebar's own collapsible tree.
+* Sub-directories of the primary collection (`wip/`, `lab/`, etc.) are
+* deliberately excluded — the header rail is for cross-collection
+* navigation; sub-sections belong in the sidebar's own tree.
 *
 * Caller must pass the *un-scoped* tree (the result of
 * `buildSidebarTree`, not `getSidebar`); otherwise only the current
@@ -557,16 +542,13 @@ function applyDefaultCollapsed(items) {
 	}
 }
 /**
-* @deprecated Effective no-op under structural separation. Pre-2026
-* Nimbus rendered the group's index as the first child link and used
-* this to rename that link to "Overview". The index is now exposed via
-* `SidebarGroupItem.indexHref` (the group label IS the link), so there's
-* no first-child index to rename. The function is kept so older configs
-* that set `sidebar.overviewLabel` don't blow up; future major can drop it.
-*
-* Renamed only when the first link IS the group's index (matched via the
-* `sortKeyByItem` WeakMap) — under structural separation that condition
-* never holds, so this silently returns the input unchanged.
+* Relabel a section's landing link to the `overviewLabel` string (default
+* "Overview"). Applies to a `directory:` autogenerate's leading landing
+* link wherever it surfaces (tracked via `directoryIndexLinks`), and to a
+* group whose first child link IS the group's own index (matched via the
+* `sortKeyByItem` WeakMap). Config groups expose their index as the group
+* label itself (`SidebarGroupItem.indexHref`), so those aren't relabelled
+* here — there's no separate child link to rename.
 */
 function applyOverviewLabel(items, label) {
 	for (const item of items) if (item.type === "link" && directoryIndexLinks.has(item)) item.label = label;
@@ -1025,7 +1007,7 @@ async function getLastUpdatedFromGit(filePath) {
 
 //#endregion
 //#region src/_internal/admonition-transform.ts
-/** Built-in MyST / Docusaurus / CF admonition types and their Aside mapping. */
+/** Built-in MyST / Docusaurus admonition types and their Aside mapping. */
 const BUILTIN_TYPES = {
 	note: "note",
 	info: "note",
@@ -1856,9 +1838,9 @@ async function validateMdxContent(options) {
 * Format a list of failures into a single multi-line error message
 * suitable for `throw new Error(...)`.
 */
-function formatFailures(failures, globalsCount) {
+function formatFailures(failures) {
 	const lines = failures.map((f) => {
-		const fix = f.hint ? `Did you mean <${f.hint} />?` : globalsCount === 0 ? `Register it in src/components.ts, or add an explicit \`import\` at the top of this file.` : `Register it in src/components.ts, or add an explicit \`import\` at the top of this file.`;
+		const fix = f.hint ? `Did you mean <${f.hint} />?` : `Register it in src/components.ts, or add an explicit \`import\` at the top of this file.`;
 		return `  ${f.filePath}:${f.line}:${f.column}  <${f.tag} />  →  ${fix}`;
 	});
 	return `[nimbus-docs] Unknown MDX component ${failures.length === 1 ? "tag" : "tags"}:\n` + lines.join("\n") + "\n\nA PascalCase tag in MDX must either be registered in src/components.ts (the global registry) or imported at the top of the file. Without either, MDX renders the tag as literal text on the page — a silent failure this validator turns into a build error.";
@@ -2086,7 +2068,7 @@ function validateNimbusConfig(input) {
 		const tail = received === null ? "" : `\n      received: ${received}`;
 		return `  - ${display}: ${issue.message}${tail}`;
 	}).join("\n");
-	throw new Error(`Invalid nimbus.config — fix these issues:\n${issues}\n\nSee https://nimbus-docs.dev/config for the full config schema.`);
+	throw new Error(`Invalid nimbus.config — fix these issues:\n${issues}\n\nSee https://nimbus-docs.com/config for the full config schema.`);
 }
 /**
 * Resolve the value at `path` inside the raw input and format it for an
@@ -2134,18 +2116,11 @@ function virtualConfigPlugin(config, extras) {
 * inside `.md` / `.mdx` files. Output feeds `shikiConfig.langs` so Shiki
 * eager-loads every grammar at startup instead of lazy-loading on first use.
 *
-* Why this matters: Shiki's lazy load assumes every MDX file gets processed
-* during a build. Layer 2 (incremental builds' Vite MDX-skip plugin) breaks
-* that assumption — cached MDX files never enter the markdown pipeline, so
-* languages that only appear in cached files would never trigger a grammar
-* load, and any non-cached file using those languages would silently render
-* without highlighting.
-*
-* Eager loading also gives non-incremental users a small predictability win:
-* the highlighter behaves the same regardless of which file is processed
-* first.
-*
-* Cost: ~1s on a 7k-file bench. Acceptable.
+* Needed because incremental builds skip cached MDX files: those never
+* enter the markdown pipeline, so a language appearing only in cached
+* files would never trigger Shiki's lazy grammar load, and a non-cached
+* file using it would render without highlighting. Eager loading also
+* keeps highlighting independent of which file is processed first.
 */
 const FENCE_RE = /^[ \t]*```([a-zA-Z][a-zA-Z0-9_+\-]*)/gm;
 async function* walkMdx(dir) {
@@ -2200,10 +2175,10 @@ async function scanCodeBlockLanguages(projectRoot, langAlias = {}) {
 *   pages/<aa>/<full-hash>.html   — cached HTML body for a page, sharded
 *                                   by the first 2 hex chars of the hash
 *
-* Phase 2 MVP — atomic per-file writes. v2 adds a manifest-level
-* `namespace` field for PR-vs-main isolation; resolution lives in
-* `namespace.ts`. Framework/Node version is folded into `globalHash` via
-* `computeGlobalHash` already, so it doesn't need a separate field.
+* Atomic per-file writes. A manifest-level `namespace` field provides
+* PR-vs-main isolation; resolution lives in `namespace.ts`. Framework/Node
+* version is folded into `globalHash` via `computeGlobalHash` already, so
+* it doesn't need a separate field.
 */
 const SCHEMA_VERSION = 2;
 var Cache = class {
@@ -2272,14 +2247,13 @@ var Cache = class {
 	/**
 	* Snapshot a *bounded subset* of `dist/_astro/` into the cache.
 	*
-	* Naive snapshot was unbounded: every warm build accumulated new
-	* bundle hashes (vite produces different hashes when the module graph
-	* differs between builds) and we kept everything forever. Caller passes
-	* the set of asset rel-paths that some cached HTML actually references —
+	* Bounded so the cache doesn't grow forever: Vite emits new bundle
+	* hashes whenever the module graph differs between builds. The caller
+	* passes the asset rel-paths that some cached HTML actually references;
 	* anything outside that set gets dropped.
 	*
 	* `referencedRelPaths` should be the union of every `/_astro/...` URL
-	* extracted from cached HTML — see `parseReferencedAssets` in index.ts.
+	* extracted from cached HTML — see `collectReferencedAssets` in index.ts.
 	*/
 	async snapshotAssets(distAstroDir, referencedRelPaths) {
 		const target = resolve(this.root, "assets");
@@ -2448,10 +2422,9 @@ async function writeAtomic(path, data) {
 *   - pageHash:    sha256(page bytes + globalHash). Determines whether a
 *                  given page's cached HTML is still valid.
 *
-* Phase 2 MVP — deliberately no partial tracking, no data-collection tracking,
-* no component-graph tracking. Phase 3 wires the partial registry into the
-* page hash; that work depends on `validate-mdx-content.ts` being extended
-* to capture `<Render file="…">` references.
+* Current scope deliberately omits data-collection tracking and
+* component-graph tracking. Partial-dependency tracking folds the partial
+* registry into the page hash (see `partial-refs.ts`).
 */
 const TRACKED_DIRS = ["src", "public"];
 const TRACKED_FILES = [
@@ -2514,7 +2487,7 @@ async function walk$1(dir, root) {
 *   - Node major version (minor diffs occasionally affect bundling)
 *   - Platform + arch (some asset emission is platform-sensitive)
 *
-* Including provenance closes BUG-002 / BUG-003: a framework upgrade
+* Including provenance closes a class of staleness bug: a framework upgrade
 * (or Node bump, or OS change) silently changed rendered output but the
 * old global hash matched, so warm builds served stale entries from a
 * different version of the world.
@@ -2583,7 +2556,7 @@ async function readDepVersion(projectRoot, dep) {
 	}
 }
 /**
-* Phase 3 — per-page hash with transitive partial dependencies folded in.
+* Per-page hash with transitive partial dependencies folded in.
 *
 * Same shape as `computePageHash` but additionally absorbs the bytes of
 * every partial the page transitively embeds. Sorted by path so two
@@ -2667,14 +2640,14 @@ async function resolveCacheNamespace(projectRoot) {
 //#endregion
 //#region src/_internal/incremental/partial-refs.ts
 /**
-* Phase 3 — partial dependency tracking.
+* Partial dependency tracking.
 *
 * Walks MDX content to find `<Render file="…" />` and `<Render slug="…" />`
 * references, then builds a per-page transitive closure: "pathname X
 * embeds partials A, B, C — where A in turn embeds D, and B in turn
 * embeds E and F." Folding all of those partials' bytes into the page's
-* hash gives us the property the spec promises: edit one partial, exactly
-* the pages that transitively embed it re-render.
+* hash gives us the property we want: edit one partial, exactly the pages
+* that transitively embed it re-render.
 *
 * Scope (v1):
 *   - Only string-literal `file` / `slug` props get captured. Dynamic
@@ -2683,16 +2656,17 @@ async function resolveCacheNamespace(projectRoot) {
 *     v1 limitation; the `partialResolver` hook (deferred) gives sites
 *     an escape valve.
 *   - Default resolver: `<Render file="topic/slug" />` resolves to
-*     `src/content/partials/topic/slug.mdx`. Matches the bench, apps/www,
-*     and mvvmm's PR shape for cloudflare-docs (their resolver also
-*     prepends a `product` prop — that needs a custom resolver).
+*     `src/content/partials/topic/slug.mdx`. Sites with a multi-prop
+*     convention (e.g. a resolver that prepends a `product` prop) need a
+*     custom resolver.
 *   - Cycles in the partial graph are handled (visited set).
 */
 /**
 * Check `candidate` is a normalised path under `rootWithSep`. Cheap
 * defense against `../` traversal escaping the partials root. We use a
 * trailing-sep marker on root to avoid false-matching `partialsRoot` with
-* `partialsRoot-evil/` style siblings.
+* sibling directories that share its name as a prefix (e.g.
+* `partialsRoot-shared/`).
 */
 function isInside(candidate, rootWithSep) {
 	return candidate.startsWith(rootWithSep) || candidate === rootWithSep.slice(0, -1);
@@ -2715,7 +2689,7 @@ const ATTR_RE = /([a-zA-Z][a-zA-Z0-9_]*)\s*=\s*["']([^"']*)["']/g;
 *     extensions or use plain Markdown for partials.
 *
 * `partialsBase` lets callers point the resolver at a non-default partials
-* collection base (closes BUG-040). Default: `src/content/partials`.
+* collection base. Default: `src/content/partials`.
 */
 function makeDefaultPartialResolver(projectRoot, partialsBase = "src/content/partials") {
 	const partialsRoot = resolve(projectRoot, partialsBase);
@@ -2884,7 +2858,7 @@ async function partialsDirExists(projectRoot, partialsBase = "src/content/partia
 //#endregion
 //#region src/_internal/incremental/index.ts
 /**
-* Incremental builds — Phase 2 MVP.
+* Incremental builds.
 *
 * Wires the cache layer into Astro's prerenderer. On warm build, pages whose
 * source bytes (and the global hash) haven't changed since the last build
@@ -2893,16 +2867,14 @@ async function partialsDirExists(projectRoot, partialsBase = "src/content/partia
 *
 * Astro sees every route in `getStaticPaths` either way — cache hits flow
 * through `astro:build:generated`, adapter writers, route-headers accounting
-* exactly like fresh renders. This is the spec's design, *not* mvvmm's
-* `getStaticPaths`-filtering approach, because the latter hides cached
-* routes from downstream hooks.
+* exactly like fresh renders. This is by design — rather than filtering
+* cached routes out of `getStaticPaths`, which would hide them from
+* downstream hooks.
 *
-* Anti-goals for this MVP (deferred to Phase 3+):
-*   - Partial-dependency tracking. Edit a partial → still full rebuild today.
+* Out of scope for now:
 *   - Data-collection scoping.
 *   - Component-graph tracking. Any tracked-file change → full rebuild.
-*   - Provenance / namespacing / trust boundary. Hardening track.
-*   - `nimbus build --explain` and structured build reports. Console log only.
+*   - `nimbus build --explain` and structured build reports.
 */
 /**
 * Normalise a request URL to its canonical pathname (no trailing slash,
@@ -2921,7 +2893,7 @@ function canonicalisePathname(input) {
 }
 /**
 * Build a map from pathname → MDX file bytes by walking the docs collection
-* directory. Phase 2 MVP only handles the primary `docs` collection.
+* directory. Only the primary `docs` collection is handled.
 *
 * Pathname derivation: `src/content/docs/<entry.id>.mdx` → `/<entry.id>`,
 * mirroring `getDocsStaticPaths` which uses `entry.id` verbatim as slug.
@@ -3019,9 +2991,9 @@ async function collectDocsPages(projectRoot, docsBase = "src/content/docs") {
 * Computes per-page hashes, reads prior manifest, determines which pages
 * are cache-hits.
 *
-* Phase 3 — the page hash includes the bytes of every partial the page
-* transitively embeds, so editing a partial invalidates exactly the pages
-* that reference it (directly or transitively) and nothing else.
+* The page hash includes the bytes of every partial the page transitively
+* embeds, so editing a partial invalidates exactly the pages that reference
+* it (directly or transitively) and nothing else.
 */
 async function setupIncrementalContext(projectRoot, cacheDir, logger, partialResolver) {
 	const cache = new Cache(cacheDir ? resolve(cacheDir, "nimbus") : resolve(projectRoot, ".nimbus/cache"));
@@ -3081,7 +3053,7 @@ async function setupIncrementalContext(projectRoot, cacheDir, logger, partialRes
 /**
 * Wrap an Astro prerenderer with the cache.
 *
-* Strategy (mvvmm-style — chosen empirically over the "wrap Response" approach
+* Strategy (chosen empirically over the "wrap Response" approach
 * because Astro's per-route work outside `render` is the actual dominant cost,
 * not MDX→HTML conversion):
 *
@@ -3094,12 +3066,12 @@ async function setupIncrementalContext(projectRoot, cacheDir, logger, partialRes
 *     `dist/<pathname>/index.html` for the filtered cached routes — Astro
 *     never wrote them, so we do.
 *
-* Trade-off vs. the spec's "wrap Response in render" design: downstream
+* Trade-off vs. the "wrap Response in render" design: downstream
 * Astro hooks (`astro:build:generated`, adapter writers, route accounting)
 * don't see cached routes. For Cloudflare adapter sites or anything that
 * depends on every route being visible to those hooks, this matters.
 * For static SSG sites where the rendered HTML *is* the output, it's fine.
-* Documented as a limitation in Phase 5 user-facing notes.
+* Documented as a known limitation.
 */
 function wrapPrerenderer(defaultPrerenderer, ctx) {
 	return {
@@ -3176,7 +3148,7 @@ async function restoreCachedPagesToDist(ctx, outDir) {
 * (so the snapshot is the union of fresh + previously-cached assets the
 * cached HTML still references).
 *
-* BUG-007 fix: bounded to assets actually referenced by cached HTML. We
+* Bounded to assets actually referenced by cached HTML. We
 * walk every cached page's bytes, regex-extract `/_astro/...` URLs,
 * dedupe — and only persist those. Without this the snapshot grew
 * unboundedly because vite produces new bundle hashes on every warm
@@ -3193,7 +3165,7 @@ const ASSET_REF_RE = /\/_astro\/([^"')\s>]+)/g;
 * Strip query string and hash from an extracted asset path. Without
 * this, `/_astro/foo.js?v=1` would record `foo.js?v=1` as the file
 * name — the snapshot would skip it because no such file exists in
-* `_astro/`, leaving the warm build with a broken reference (BUG-108).
+* `_astro/`, leaving the warm build with a broken reference.
 */
 function normaliseAssetRef(raw) {
 	if (!raw) return null;
@@ -3213,10 +3185,9 @@ function normaliseAssetRef(raw) {
 *
 * The single regex matches `/_astro/...` anywhere in the HTML —
 * straightforward for `href="..."`, `src="..."`, `url(...)` in inline
-* styles, and individual `srcset` URLs alike. (BUG-107 was about the
-* earlier regex anchoring on a quote/paren prefix and missing the
-* second+nth URL inside a `srcset` value; the unanchored form here
-* catches them all.)
+* styles, and individual `srcset` URLs alike. (An earlier regex
+* anchored on a quote/paren prefix and missed the second+nth URL
+* inside a `srcset` value; the unanchored form here catches them all.)
 *
 * We scan the dist output rather than the in-memory cache because dist
 * is the source of truth for what's currently referenced — after the
@@ -3335,8 +3306,8 @@ function mdxSkipPlugin(ctx) {
 *   - sitemap-0.xml carries all entries (we don't split until >45k urls)
 *   - sitemap-index.xml lists sitemap-0.xml only
 *
-* v1 scope — no custom `serialize` yet (deferred; cloudflare-docs case),
-* no `lastmod`, `changefreq`, `priority`, no image/video sitemaps. Matches
+* Scope: an optional `serialize` hook per URL, but no `lastmod`,
+* `changefreq`, `priority`, and no image/video sitemaps. Matches
 * `@astrojs/sitemap` *default* output for sites that don't override.
 */
 const URLSET_XMLNS = "xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\" xmlns:news=\"http://www.google.com/schemas/sitemap-news/0.9\" xmlns:xhtml=\"http://www.w3.org/1999/xhtml\" xmlns:image=\"http://www.google.com/schemas/sitemap-image/1.1\" xmlns:video=\"http://www.google.com/schemas/sitemap-video/1.1\"";
@@ -3487,8 +3458,7 @@ function extractFrontmatter(source) {
 	const rest = source.slice(afterFirstMarker + 1);
 	const closingMatch = rest.match(/(^|\n)---\s*(\n|$)/);
 	if (!closingMatch || closingMatch.index === void 0) return null;
-	const endIndex = closingMatch[1] === "\n" ? closingMatch.index : closingMatch.index;
-	return rest.slice(0, endIndex);
+	return rest.slice(0, closingMatch.index);
 }
 /**
 * Find a top-level boolean field in YAML frontmatter. Returns the
@@ -3519,9 +3489,8 @@ function parseBoolField(yaml, field) {
 *   - `string[]` for either array form
 *   - `undefined` if absent
 *
-* The multiline form is the canonical YAML list syntax; the scanner
-* previously accepted only scalar and inline-array, which silently
-* dropped valid block lists at build time. The schema validates the
+* All three forms are accepted: scalar, inline array, and the multiline
+* block list (canonical YAML list syntax). The schema validates the
 * post-parse shape; the scanner has to match it.
 */
 function parsePreviousSlugField(yaml) {
@@ -3824,7 +3793,7 @@ function nimbus(rawConfig, options = {}) {
 							skip: validateOpts.skip,
 							projectRoot
 						});
-						if (failures.length > 0) throw new Error(formatFailures(failures, globals.length));
+						if (failures.length > 0) throw new Error(formatFailures(failures));
 						logger.info(`MDX validation passed — ${globals.length} global component${globals.length === 1 ? "" : "s"} registered, ${contentDirs.length} content dir${contentDirs.length === 1 ? "" : "s"} scanned.`);
 					}
 				}
@@ -4075,9 +4044,9 @@ function runPagefind(siteDir) {
 /**
 * Main entry for `nimbus-docs`.
 *
-* Exports the Astro integration (default), config helper, and the four
-* data helpers (sidebar, prev/next, breadcrumbs, TOC). Phase 6 will
-* add page composition helpers (`getDocsStaticPaths`, `getDocsPageProps`).
+* Exports the Astro integration (default), config helper, the data helpers
+* (sidebar, prev/next, breadcrumbs, TOC), and the page composition helpers
+* (`getDocsStaticPaths`, `getDocsPageProps`).
 *
 * Helpers read the user's config from `virtual:nimbus/config` (provided
 * by our Vite plugin) and content entries from `astro:content`. Both
@@ -4326,7 +4295,7 @@ async function getPrevNext(currentSlug, options) {
 /**
 * Build breadcrumb trail from "/" to the current page.
 *
-* Phase 5: simple URL-segment derivation. Later phases may enrich with
+* Simple URL-segment derivation. A later iteration may enrich this with
 * sidebar-aware labels.
 */
 async function getBreadcrumbs(currentSlug, options) {