dogsbay 0.2.0-beta.35 → 0.2.0-beta.36

package/dist/audit/lib/collect-assets.js

@@ -0,0 +1,64 @@
+/**
+ * Walk one or more content directories collecting absolute-path
+ * asset references that the build's `copyAssets` would emit to
+ * `public/`. The audit rule `structure/asset-refs` cross-checks
+ * `<img src>` / `<a href>` references against this set so a
+ * misnamed file shows up as a structured Issue.
+ *
+ * Mirrors the extension set used by `copyAssets` in
+ * `@dogsbay/format-astro/src/project.ts`. Keep in sync — drift
+ * would either flag valid refs as broken or miss real misses.
+ */
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+// Same sets as format-astro's copyAssets. Keep in sync.
+const OPTIMIZABLE_EXTS = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp"]);
+const PASSTHROUGH_EXTS = new Set([".svg", ".ico", ".pdf"]);
+/**
+ * Return the set of absolute asset paths (leading slash) that
+ * `copyAssets` would emit for the given content directories.
+ *
+ * @param contentDirs Absolute paths, one per source.
+ */
+export function collectAssets(contentDirs) {
+    const out = new Set();
+    for (const dir of contentDirs) {
+        if (!existsSync(dir))
+            continue;
+        walk(dir, dir, out);
+    }
+    return out;
+}
+function walk(rootDir, dir, out) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const full = join(dir, entry);
+        let isDir = false;
+        try {
+            isDir = statSync(full).isDirectory();
+        }
+        catch {
+            continue;
+        }
+        if (isDir) {
+            walk(rootDir, full, out);
+            continue;
+        }
+        const dot = entry.lastIndexOf(".");
+        if (dot < 0)
+            continue;
+        const ext = entry.slice(dot).toLowerCase();
+        if (!OPTIMIZABLE_EXTS.has(ext) && !PASSTHROUGH_EXTS.has(ext))
+            continue;
+        const rel = relative(rootDir, full);
+        // Public URL is "/<rel>" with forward slashes — copyAssets
+        // copies rel-to-source verbatim into public/.
+        out.add("/" + rel.replace(/\\/g, "/"));
+    }
+}

package/dist/audit/lib/validate-refs.js

@@ -0,0 +1,132 @@
+const EXTERNAL_RE = /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i;
+const ANCHOR_ONLY_RE = /^#/;
+const DATA_URI_RE = /^data:/i;
+const ASSET_EXT_RE = /\.(png|jpe?g|gif|webp|svg|avif|pdf|zip|csv|tsv|json|yml|yaml|toml|mp4|webm|mp3|ogg|woff2?|ttf|otf)$/i;
+/**
+ * Heuristic for "looks like an asset reference," used to decide
+ * whether an `<a href>` should be validated against the asset
+ * set or the page set. Image src is always asset; href can be
+ * either. Anything ending in a known asset extension is treated
+ * as asset.
+ */
+function looksLikeAsset(href) {
+    // Strip query + fragment before checking extension
+    const noFragment = href.split(/[?#]/)[0];
+    return ASSET_EXT_RE.test(noFragment);
+}
+export function validateRefs(pages, options) {
+    const basePath = options.basePath.replace(/\/$/, "");
+    const knownAssets = options.knownAssets;
+    // Page slug set — multiple match forms so the validator
+    // accepts the common ways authors write the same slug.
+    // For slug "tutorials/quickstart" any of these match:
+    //   /tutorials/quickstart
+    //   /tutorials/quickstart/
+    //   /tutorials/quickstart.md
+    //   /<basePath>/tutorials/quickstart   (and the above three)
+    const pageSlugs = new Set();
+    for (const p of pages) {
+        pageSlugs.add(p.slug);
+        // Index pages can be referenced as their parent dir
+        if (p.slug === "index")
+            pageSlugs.add("");
+        if (p.slug.endsWith("/index")) {
+            pageSlugs.add(p.slug.slice(0, -"/index".length));
+        }
+    }
+    const result = { linkMisses: [], assetMisses: [] };
+    for (const page of pages) {
+        walkTree(page.tree, (href, kind) => {
+            check(href, kind, page.slug, basePath, pageSlugs, knownAssets, result);
+        });
+    }
+    return result;
+}
+/** Internal walk — invokes `visit` for every href/src in the tree. */
+function walkTree(nodes, visit) {
+    for (const node of nodes) {
+        if (node.inline)
+            walkInline(node.inline, visit);
+        if (node.html)
+            walkHtml(node.html, visit);
+        if (node.props?.href && typeof node.props.href === "string") {
+            visit(node.props.href, "link");
+        }
+        if (node.props?.src && typeof node.props.src === "string") {
+            visit(node.props.src, "image");
+        }
+        if (node.children)
+            walkTree(node.children, visit);
+    }
+}
+function walkInline(nodes, visit) {
+    for (const node of nodes) {
+        if (node.type === "link" && typeof node.href === "string") {
+            visit(node.href, "link");
+            if (node.children)
+                walkInline(node.children, visit);
+        }
+        else if (node.type === "image" && typeof node.src === "string") {
+            visit(node.src, "image");
+        }
+        else if (node.type === "highlight" && node.children) {
+            walkInline(node.children, visit);
+        }
+    }
+}
+function walkHtml(html, visit) {
+    // Pre-rendered HTML in `node.html` (Starlight importer output,
+    // MkDocs raw HTML, etc.) — scan with regexes. Cheap; the audit
+    // doesn't need a full HTML parser for this.
+    const aRe = /<a\b[^>]*\shref="([^"]+)"/gi;
+    let m;
+    while ((m = aRe.exec(html)) !== null)
+        visit(m[1], "link");
+    const imgRe = /<img\b[^>]*\ssrc="([^"]+)"/gi;
+    while ((m = imgRe.exec(html)) !== null)
+        visit(m[1], "image");
+}
+function check(href, kind, pageSlug, basePath, pageSlugs, knownAssets, result) {
+    if (!href || EXTERNAL_RE.test(href))
+        return;
+    if (ANCHOR_ONLY_RE.test(href))
+        return;
+    if (DATA_URI_RE.test(href))
+        return;
+    if (!href.startsWith("/"))
+        return; // relative — out of scope for v1
+    // Strip query and fragment for the comparison.
+    const cleanHref = href.split(/[?#]/)[0];
+    // Strip basePath if the author prefixed it. We compare against
+    // bare slugs, so `/docs/intro` and `/intro` should both match
+    // page slug "intro" (basePath="/docs").
+    let path = cleanHref;
+    if (basePath && (path === basePath || path.startsWith(`${basePath}/`))) {
+        path = path.slice(basePath.length);
+    }
+    // Strip leading / and trailing /, plus the `.md` extension.
+    let trimmed = path.replace(/^\//, "").replace(/\/$/, "");
+    trimmed = trimmed.replace(/\.md$/i, "");
+    // Image src — always asset.
+    // Anchor href — asset if it has an asset extension, else page.
+    const wantsAsset = kind === "image" || looksLikeAsset(cleanHref);
+    if (wantsAsset) {
+        // Asset paths are absolute under the public root.
+        // knownAssets stores entries like "/_assets/foo.png".
+        const lookup = cleanHref.startsWith("/") && basePath && cleanHref.startsWith(`${basePath}/`)
+            ? cleanHref.slice(basePath.length)
+            : cleanHref;
+        if (!knownAssets.has(lookup)) {
+            result.assetMisses.push({
+                pageSlug,
+                href,
+                resolvedAgainst: "asset",
+            });
+        }
+        return;
+    }
+    // Page lookup
+    if (!pageSlugs.has(trimmed)) {
+        result.linkMisses.push({ pageSlug, href, resolvedAgainst: "page" });
+    }
+}

package/dist/audit/rules/structure/asset-refs.js

@@ -0,0 +1,41 @@
+import { validateRefs } from "../../lib/validate-refs.js";
+export const assetRefs = {
+    id: "structure/asset-refs",
+    category: "structure",
+    stage: "source-corpus",
+    severity: "error",
+    description: "Every absolute `<img src>` and asset-style `<a href>` resolves to a file under the content tree.",
+    run(rawCtx) {
+        const ctx = rawCtx;
+        if (!ctx.pages || ctx.pages.length === 0)
+            return [];
+        if (!ctx.knownAssets) {
+            // No asset set available — typically a unit-test ctx that
+            // didn't bother. No-op rather than false-positive.
+            return [];
+        }
+        const { assetMisses } = validateRefs(ctx.pages, {
+            basePath: ctx.basePath ?? "",
+            knownAssets: ctx.knownAssets,
+        });
+        return assetMisses.map((m) => {
+            // Where the user should drop the file to satisfy THIS ref —
+            // strip optional basePath, prepend `content` for the
+            // suggestion. (We can't know the exact content dir layout
+            // for multi-source sites without more plumbing; keep it
+            // intuitive.)
+            const cleanHref = m.href.split(/[?#]/)[0];
+            const expected = `content${cleanHref}`;
+            return {
+                ruleId: "structure/asset-refs",
+                severity: "error",
+                file: `${m.pageSlug}.md`,
+                message: `Asset reference ${m.href} doesn't match any file in the ` +
+                    `content tree. To fix: correct the path, rename the ` +
+                    `existing file to match, or drop the asset at ` +
+                    `${expected} to satisfy this exact reference.`,
+                context: m.href,
+            };
+        });
+    },
+};

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

@@ -11,6 +11,8 @@
  *   - structure/duplicate-slugs      (corpus; two sources produced the same URL)
  */
 import { registerRule } from "../../registry.js";
+import { assetRefs } from "./asset-refs.js";
+import { internalLinks } from "./internal-links.js";
 import { localeCoherence } from "./locale-coherence.js";
 import { namespaceCoherence } from "./namespace-coherence.js";
 import { navTargetExists } from "./nav-target-exists.js";
@@ -28,6 +30,8 @@ export function registerStructureRules() {
     registerRule(versionCoherence);
     registerRule(localeCoherence);
     registerRule(navTargetExists);
+    registerRule(internalLinks);
+    registerRule(assetRefs);
 }
 /**
  * Test-only: reset the "registered" flag so unit tests can

package/dist/audit/rules/structure/internal-links.js

@@ -0,0 +1,28 @@
+import { validateRefs } from "../../lib/validate-refs.js";
+export const internalLinks = {
+    id: "structure/internal-links",
+    category: "structure",
+    stage: "source-corpus",
+    severity: "error",
+    description: "Every absolute internal `<a href>` resolves to a built page in the corpus.",
+    run(rawCtx) {
+        const ctx = rawCtx;
+        if (!ctx.pages || ctx.pages.length === 0)
+            return [];
+        const { linkMisses } = validateRefs(ctx.pages, {
+            basePath: ctx.basePath ?? "",
+            knownAssets: ctx.knownAssets ?? new Set(),
+        });
+        return linkMisses.map((m) => ({
+            ruleId: "structure/internal-links",
+            severity: "error",
+            file: `${m.pageSlug}.md`,
+            message: `Internal link to ${m.href} doesn't resolve to any built ` +
+                `page. To fix: correct the path, rename the target page ` +
+                `to match, or remove the link. (Common cause: page renamed ` +
+                `without updating the body text. ` +
+                `Use \`dogsbay site check\` to surface every miss.)`,
+            context: m.href,
+        }));
+    },
+};

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

@@ -78,7 +78,9 @@ export const navTargetExists = {
                     severity: "error",
                     file: navPath,
                     message: `Nav references missing file: ${miss.file} ` +
-                        `(resolved to ${miss.resolvedAbs}). Fix the path or remove the entry.`,
+                        `(resolved to ${miss.resolvedAbs}). To fix: rename the ` +
+                        `file to match, correct the path in the nav file, or ` +
+                        `remove the entry.`,
                     context: miss.file,
                 });
             }

package/dist/audit/run.js

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

package/dist/commands/site-build.js

@@ -22,6 +22,8 @@ import { collectPassthroughEntries } from "../passthrough-astro.js";
 import { configToAstroOptions, findConfig, loadConfig, resolveOutputDir, } from "../config/index.js";
 import { filterSourcesForMode, importContent, primaryModeFiltersAnything, } from "../import-content.js";
 import { resolveSource } from "../source-resolver.js";
+import { collectAssets } from "../audit/lib/collect-assets.js";
+import { validateRefs } from "../audit/lib/validate-refs.js";
 import { loadPlugins, runExtendConfig, runOnContentImported, runTransformNav, runEmitFiles, collectClientModules, collectStyles, collectClientConfigs, collectComponentWrappers, } from "../plugins/index.js";
 export async function siteBuild(cwd, options) {
     const startDir = resolve(cwd || ".");
@@ -137,7 +139,15 @@ export async function siteBuild(cwd, options) {
         console.log(`  Output: ${outputDir}`);
     }
     // 7. Import content
-    const importResult = await importContent(resolvedSources, config);
+    //
+    // `--strict` promotes nav-target misses to fatal at build time
+    // (default: warn + label-only fallback, soft). Plumbed through
+    // importContent → plugin → buildNavFromDirectory → loadNavFile
+    // via the `missingNavTargets: "fail"` import option. See
+    // plans/site-build-strict.md.
+    const importResult = await importContent(resolvedSources, config, {
+        missingNavTargets: options.strict ? "fail" : undefined,
+    });
     const { importer } = importResult;
     // Filter status: draft pages from production builds. dogsbay site
     // dev passes includeDrafts: true so drafts stay visible during
@@ -161,6 +171,38 @@ export async function siteBuild(cwd, options) {
             : draftCount > 0
                 ? ` (including ${draftCount} draft${draftCount === 1 ? "" : "s"})`
                 : ""));
+    // 7d. --strict ref validation. Phase 2 of plans/site-build-strict.md.
+    // Same logic as the structure/internal-links + structure/asset-refs
+    // audit rules — single source of truth in validateRefs. Under
+    // --strict, the first miss throws; without it, site check is the
+    // surface for these (build stays soft to preserve the dev loop).
+    if (options.strict === true) {
+        const knownAssets = collectAssets(resolvedSources);
+        const { linkMisses, assetMisses } = validateRefs(pages, {
+            basePath: config.site.basePath ?? "",
+            knownAssets,
+        });
+        if (linkMisses.length > 0) {
+            const m = linkMisses[0];
+            throw new Error(`Internal link to ${m.href} from ${m.pageSlug}.md doesn't ` +
+                `resolve to any built page. To fix: correct the path, rename ` +
+                `the target page to match, or remove the link.` +
+                (linkMisses.length > 1
+                    ? ` (${linkMisses.length - 1} more found — run \`dogsbay site check\` for the full list.)`
+                    : ""));
+        }
+        if (assetMisses.length > 0) {
+            const m = assetMisses[0];
+            const cleanHref = m.href.split(/[?#]/)[0];
+            throw new Error(`Asset reference ${m.href} from ${m.pageSlug}.md doesn't ` +
+                `match any file in the content tree. To fix: correct the ` +
+                `path, rename the existing file to match, or drop the asset ` +
+                `at content${cleanHref} to satisfy this exact reference.` +
+                (assetMisses.length > 1
+                    ? ` (${assetMisses.length - 1} more found — run \`dogsbay site check\` for the full list.)`
+                    : ""));
+        }
+    }
     // 7. Emit content / config-derived / agent-readiness tiers.
     // sourceDir drives asset copying + relative extraCss resolution.
     // PR 1 ships a single-source pipeline; the namespace PR will

package/dist/commands/site-check.js

@@ -23,6 +23,7 @@ import pc from "picocolors";
 import { configToAstroOptions, findConfig, loadConfig, resolveOutputDir, } from "../config/index.js";
 import { effectiveLocale, effectiveVersion, importContent, isLocaleAxisActive, isNamespaceAxisActive, isVersionAxisActive, } from "../import-content.js";
 import { resolveSource } from "../source-resolver.js";
+import { collectAssets } from "../audit/lib/collect-assets.js";
 import { filterRules, registerRule } from "../audit/registry.js";
 import { reportExitCode, runAudit } from "../audit/run.js";
 import { loadPlugins, collectAuditRules, runOnContentImported, runTransformNav, } from "../plugins/index.js";
@@ -189,6 +190,12 @@ export async function siteCheck(cwd, options) {
         const r = await resolveSource(src, siteRoot);
         auditSources.push({ contentDir: r.path, navOverride: src.nav });
     }
+    // Asset set for `structure/asset-refs` — walks every source's
+    // content tree for files matching `copyAssets`'s extension
+    // list. Keep `collectAssets` in sync with that helper or refs
+    // either false-positive (real assets flagged) or false-negative
+    // (real misses missed).
+    const knownAssets = collectAssets(auditSources.map((s) => s.contentDir));
     const report = runAudit({
         rules,
         pages,
@@ -201,6 +208,8 @@ export async function siteCheck(cwd, options) {
         locales,
         auditSources,
         siteRoot,
+        basePath: config.site.basePath,
+        knownAssets,
     });
     // ── Output ─────────────────────────────────────────────────────
     if (!options.quiet) {

package/dist/import-content.js

@@ -180,25 +180,7 @@ export function primaryModeFiltersAnything(sources) {
             primaryCount++;
     return primaryCount > 0 && primaryCount < sources.length;
 }
-/**
- * Run the import pipeline for a Dogsbay site.
- *
- * Loops over `config.content.sources[]`, resolving each to a
- * filesystem path, picking its importer, and calling its
- * `import()`. Pages and nav are concatenated in declaration order.
- *
- * In PR 1 only the `path:` origin is supported and only single-
- * element `sources[]` is exercised in practice; the loop shape sets
- * up multi-source aggregation for the namespace / versioning /
- * i18n PRs.
- *
- * @param resolvedSources - absolute paths to each source's content
- *   directory, in the same order as `config.content.sources[]`. The
- *   caller is responsible for resolving relative source paths
- *   against the config-file dir before invoking.
- * @param config - resolved DogsbayConfig (defaults applied)
- */
-export async function importContent(resolvedSources, config) {
+export async function importContent(resolvedSources, config, options = {}) {
     const sources = config.content.sources;
     if (sources.length === 0) {
         throw new Error("config.content.sources must contain at least one source");
@@ -228,7 +210,7 @@ export async function importContent(resolvedSources, config) {
         }
         if (!firstImporter)
             firstImporter = importer;
-        const opts = buildImportOptions(config, sourceCfg);
+        const opts = buildImportOptions(config, sourceCfg, options);
         const { pages, nav } = await importer.import(resolved, opts);
         const anyAxisActive = axes.version || axes.namespace || axes.locale;
         const prefixSegs = getPrefixSegments(sourceCfg, axes, defaults);
@@ -374,7 +356,7 @@ function resolveImporter(source, fromName) {
  * top-level fields (`section`, `codeBlockTitle`) apply to all
  * sources.
  */
-function buildImportOptions(config, source) {
+function buildImportOptions(config, source, extra = {}) {
     const opts = {};
     if (source.nav)
         opts.nav = source.nav;
@@ -386,6 +368,9 @@ function buildImportOptions(config, source) {
     if (config.content.diagrams !== undefined) {
         opts.diagrams = config.content.diagrams;
     }
+    if (extra.missingNavTargets !== undefined) {
+        opts.missingNavTargets = extra.missingNavTargets;
+    }
     // MkDocs-specific
     if (source.mkdocs?.partialsDir) {
         opts.partialsDir = source.mkdocs.partialsDir;

package/dist/index.js

@@ -117,6 +117,10 @@ site
     "Kept as a no-op for compatibility with older scripts.")
     .option("--refresh", "Wipe the per-source git cache before resolving — forces re-clone of every git: source. " +
     "Useful when a tracked branch's HEAD has moved.")
+    .option("--strict", "Fail the build on structural breakage — missing nav targets, " +
+    "malformed nav files. Recommended for CI. One flag, growing " +
+    "coverage; release notes call out additions. See " +
+    "plans/site-build-strict.md.")
     .action((dir, options) => siteBuild(dir, options));
 site
     .command("dev")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dogsbay",
-  "version": "0.2.0-beta.35",
+  "version": "0.2.0-beta.36",
   "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-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"
+    "@dogsbay/format-mkdocs": "0.2.0-beta.36",
+    "@dogsbay/format-obsidian": "0.2.0-beta.36",
+    "@dogsbay/format-astro": "0.2.0-beta.36",
+    "@dogsbay/format-mdx": "0.2.0-beta.36",
+    "@dogsbay/format-starlight": "0.2.0-beta.36",
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.36",
+    "@dogsbay/format-openapi": "0.2.0-beta.36",
+    "@dogsbay/types": "0.2.0-beta.36"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",