dogsbay 0.2.0-beta.33 → 0.2.0-beta.35

package/dist/audit/rules/seo/sitemap.js

@@ -123,7 +123,7 @@ export const sitemapComplete = {
     severity: "warning",
     description: "Every built HTML page is listed in the sitemap.",
     run(ctx) {
-        const { file, distRoot, allFiles } = ctx;
+        const { file, distRoot, allFiles, config } = ctx;
         const state = getState(distRoot);
         // Emit once per audit run — we have access to allFiles here.
         if (state.emitted.has("seo/sitemap-complete"))
@@ -134,13 +134,22 @@ export const sitemapComplete = {
             // to add here.
             return [];
         }
+        // urlBase comes from the path component of site.url. When the
+        // site is mounted at a subpath (typical GH Pages project deploy:
+        // `site.url: https://user.github.io/repo`), sitemap entries
+        // carry the urlBase prefix (the emitter writes absolute URLs),
+        // but the filesystem-derived urlPath below doesn't — files
+        // live at `dist/<page>/index.html` regardless of urlBase. Pass
+        // urlBase into the comparison so the suffix-strip step
+        // accounts for it. See plans/sitemap-audit-urlbase.md.
+        const urlBase = urlBaseFromSiteUrl(config?.siteUrl);
         // Map each html file to its likely "page URL" form. Astro
         // emits `docs/intro/index.html` for the URL `/docs/intro/`,
         // so we strip `/index.html` and ensure a leading slash.
         const issues = [];
         for (const f of allFiles) {
             const expectedPath = htmlPathToUrlPath(f.path);
-            const found = pathListedInSitemap(expectedPath, state.sitemapLocs);
+            const found = pathListedInSitemap(expectedPath, state.sitemapLocs, urlBase);
             if (!found) {
                 issues.push({
                     ruleId: "seo/sitemap-complete",
@@ -216,9 +225,18 @@ function htmlPathToUrlPath(htmlPath) {
  * Sitemap entries can be absolute (`https://example.com/foo/`)
  * or relative (`/foo/`); we match either by suffix.
  *
+ * `urlBase` is the path component of `site.url` — e.g. `/repo` for
+ * a GH Pages project deploy at `https://user.github.io/repo`. When
+ * non-empty, the platform's sitemap emitter writes absolute URLs
+ * including that segment (`https://user.github.io/repo/intro/`),
+ * but the filesystem-derived `urlPath` doesn't have it (files live
+ * at `dist/intro/index.html`). Strip the urlBase off the sitemap
+ * suffix before comparing so the audit doesn't flag every page as
+ * missing on every subpath-mounted deploy.
+ *
  * Trailing slash tolerant: `/foo/` matches `/foo` too.
  */
-function pathListedInSitemap(urlPath, locs) {
+function pathListedInSitemap(urlPath, locs, urlBase) {
     for (const loc of locs) {
         if (loc === urlPath)
             return true;
@@ -230,6 +248,16 @@ function pathListedInSitemap(urlPath, locs) {
             if (afterHost >= 0)
                 suffix = loc.slice(afterHost);
         }
+        // Strip the urlBase prefix when the sitemap entry carries one
+        // and the comparison target doesn't.
+        if (urlBase) {
+            if (suffix === urlBase) {
+                suffix = "/";
+            }
+            else if (suffix.startsWith(`${urlBase}/`)) {
+                suffix = suffix.slice(urlBase.length);
+            }
+        }
         if (suffix === urlPath)
             return true;
         // Trailing-slash flexibility
@@ -238,3 +266,21 @@ function pathListedInSitemap(urlPath, locs) {
     }
     return false;
 }
+/**
+ * Extract the path component of `site.url` for use as the urlBase
+ * stripping prefix. Returns `""` when site.url is missing, has no
+ * path, or doesn't parse — comparison falls back to today's
+ * behaviour.
+ */
+function urlBaseFromSiteUrl(siteUrl) {
+    if (!siteUrl)
+        return "";
+    try {
+        const u = new URL(siteUrl);
+        const path = u.pathname.replace(/\/$/, "");
+        return path === "/" ? "" : path;
+    }
+    catch {
+        return "";
+    }
+}

package/dist/audit/rules/structure/index.js

@@ -13,6 +13,7 @@
 import { registerRule } from "../../registry.js";
 import { localeCoherence } from "./locale-coherence.js";
 import { namespaceCoherence } from "./namespace-coherence.js";
+import { navTargetExists } from "./nav-target-exists.js";
 import { versionCoherence } from "./version-coherence.js";
 let registered = false;
 /**
@@ -26,6 +27,7 @@ export function registerStructureRules() {
     registerRule(namespaceCoherence);
     registerRule(versionCoherence);
     registerRule(localeCoherence);
+    registerRule(navTargetExists);
 }
 /**
  * Test-only: reset the "registered" flag so unit tests can

package/dist/audit/rules/structure/nav-target-exists.js

@@ -0,0 +1,105 @@
+/**
+ * `structure/nav-target-exists` — every `file:` reference in a
+ * declared nav file resolves to a content file on disk.
+ *
+ * Re-runs the same resolution `loadNavFile` does at build time,
+ * but in `collect` mode: instead of `console.warn` + label-only
+ * fallback (the build-pipeline behaviour), the audit surfaces
+ * every miss as a structured Issue. This is what makes nav-file
+ * typos:
+ *
+ *   - count in the `dogsbay site check` summary
+ *   - bump the exit code (error severity)
+ *   - get categorised under `structure` for selective opt-out
+ *
+ * Without this rule, a misnamed file in nav.yml emitted a
+ * `[dogsbay] Nav file references missing file: ...` line to
+ * stderr during build but never entered the audit catalog, so
+ * CI couldn't catch it. Reported by the docs team against
+ * dogsbay-docs-platform.
+ *
+ * Source content + nav heuristic: matches `buildNavFromDirectory`
+ * — an explicit `source.nav` path wins, otherwise we look for
+ * `nav.yml` / `nav.yaml` / `nav.json` in the resolved content
+ * dir. If no nav file is present, the rule is a no-op (the site
+ * uses directory-scan nav, which has its own validation in the
+ * importer).
+ */
+import { existsSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { loadNavFile } from "@dogsbay/format-dogsbay-md";
+const HEURISTIC_NAV_FILES = ["nav.yml", "nav.yaml", "nav.json"];
+export const navTargetExists = {
+    id: "structure/nav-target-exists",
+    category: "structure",
+    stage: "source-corpus",
+    severity: "error",
+    description: "Every `file:` reference in nav files (nav.yml / nav.yaml / nav.json) resolves to a content file that exists on disk.",
+    run(rawCtx) {
+        const ctx = rawCtx;
+        const auditSources = ctx.auditSources;
+        const siteRoot = ctx.siteRoot;
+        if (!auditSources || auditSources.length === 0 || !siteRoot) {
+            // No way to find nav files — typically a unit-test run with
+            // pre-imported nav.
+            return [];
+        }
+        const issues = [];
+        for (const src of auditSources) {
+            const { contentDir, navOverride } = src;
+            const navPath = resolveNavFile(navOverride, contentDir, siteRoot);
+            if (!navPath)
+                continue; // directory-scan source → skip
+            // Use `collect` mode so the loader pushes structured
+            // findings to onMissingTarget instead of console.warn'ing.
+            const misses = [];
+            try {
+                loadNavFile(navPath, contentDir, {
+                    missingFile: "collect",
+                    onMissingTarget: (m) => misses.push(m),
+                });
+            }
+            catch (err) {
+                // Nav file itself is unreadable / malformed — emit as a
+                // distinct issue. The build's heuristic-loader warns and
+                // falls back to directory scan; the audit makes the
+                // condition visible.
+                issues.push({
+                    ruleId: "structure/nav-target-exists",
+                    severity: "error",
+                    file: navPath,
+                    message: `Nav file ${navPath} failed to load: ${err.message}`,
+                });
+                continue;
+            }
+            for (const miss of misses) {
+                issues.push({
+                    ruleId: "structure/nav-target-exists",
+                    severity: "error",
+                    file: navPath,
+                    message: `Nav references missing file: ${miss.file} ` +
+                        `(resolved to ${miss.resolvedAbs}). Fix the path or remove the entry.`,
+                    context: miss.file,
+                });
+            }
+        }
+        return issues;
+    },
+};
+/**
+ * Mirror the resolution `buildNavFromDirectory` uses:
+ *   1. Explicit `source.nav` wins (relative to siteRoot)
+ *   2. Auto-detect nav.{yml,yaml,json} in the resolved content dir
+ *   3. Otherwise undefined (directory-scan nav — no nav file to audit)
+ */
+function resolveNavFile(navOverride, contentDir, siteRoot) {
+    if (navOverride) {
+        return isAbsolute(navOverride) ? navOverride : resolve(siteRoot, navOverride);
+    }
+    for (const fileName of HEURISTIC_NAV_FILES) {
+        const candidate = join(contentDir, fileName);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return undefined;
+}

package/dist/audit/run.js

@@ -28,6 +28,8 @@ export function runAudit(inputs) {
                 namespaces: inputs.namespaces,
                 versions: inputs.versions,
                 locales: inputs.locales,
+                auditSources: inputs.auditSources,
+                siteRoot: inputs.siteRoot,
             };
             for (const issue of rule.run(ctx)) {
                 issues.push(issue);

package/dist/commands/site-check.js

@@ -179,6 +179,16 @@ export async function siteCheck(cwd, options) {
             .map((s) => effectiveLocale(s, config.content.defaultLocale))
             .filter((l) => l !== undefined))
         : undefined;
+    // Re-resolve content sources for `structure/nav-target-exists`.
+    // The rule walks each source's nav file and re-runs the
+    // `file:` resolution that `loadNavFile` does at build time,
+    // surfacing misses as structured audit issues (the build-time
+    // `console.warn` doesn't enter the summary or exit code).
+    const auditSources = [];
+    for (const src of config.content.sources) {
+        const r = await resolveSource(src, siteRoot);
+        auditSources.push({ contentDir: r.path, navOverride: src.nav });
+    }
     const report = runAudit({
         rules,
         pages,
@@ -189,6 +199,8 @@ export async function siteCheck(cwd, options) {
         namespaces,
         versions,
         locales,
+        auditSources,
+        siteRoot,
     });
     // ── Output ─────────────────────────────────────────────────────
     if (!options.quiet) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dogsbay",
-  "version": "0.2.0-beta.33",
+  "version": "0.2.0-beta.35",
   "description": "CLI for Dogsbay — scaffold, build, and serve documentation sites with markdown / MkDocs / Obsidian / OpenAPI sources",
   "type": "module",
   "bin": {
@@ -32,14 +32,14 @@
     "picocolors": "^1.1.0",
     "prompts": "^2.4.2",
     "yaml": "^2.8.3",
-    "@dogsbay/format-mkdocs": "0.2.0-beta.33",
-    "@dogsbay/format-astro": "0.2.0-beta.33",
-    "@dogsbay/format-obsidian": "0.2.0-beta.33",
-    "@dogsbay/format-mdx": "0.2.0-beta.33",
-    "@dogsbay/format-starlight": "0.2.0-beta.33",
-    "@dogsbay/format-openapi": "0.2.0-beta.33",
-    "@dogsbay/types": "0.2.0-beta.33",
-    "@dogsbay/format-dogsbay-md": "0.2.0-beta.33"
+    "@dogsbay/format-obsidian": "0.2.0-beta.35",
+    "@dogsbay/format-astro": "0.2.0-beta.35",
+    "@dogsbay/format-mkdocs": "0.2.0-beta.35",
+    "@dogsbay/format-mdx": "0.2.0-beta.35",
+    "@dogsbay/format-starlight": "0.2.0-beta.35",
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.35",
+    "@dogsbay/types": "0.2.0-beta.35",
+    "@dogsbay/format-openapi": "0.2.0-beta.35"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",