dogsbay 0.2.0-beta.12 → 0.2.0-beta.121

package/dist/audit/deliverable-vars.d.ts

@@ -0,0 +1,18 @@
+import type { Issue } from "@dogsbay/site-check";
+/**
+ * Root identifiers referenced by an expression: quoted strings and
+ * dotted property tails stripped, reserved words and numbers excluded.
+ * `platform == "win" and product.name` → {platform, product}.
+ */
+export declare function expressionIdentifiers(expr: string): Set<string>;
+export interface DeliverableVarsOptions {
+    /** Resolved source content directories to scan. */
+    contentDirs: string[];
+    /** The deliverable's merged attribute context. */
+    attributes: Record<string, unknown>;
+    /** Deliverable name, for the message. */
+    deliverable: string;
+    /** Paths in issues are made relative to this root. */
+    siteRoot: string;
+}
+export declare function auditDeliverableVariables(options: DeliverableVarsOptions): Promise<Issue[]>;

package/dist/audit/deliverable-vars.js

@@ -0,0 +1,143 @@
+/**
+ * Undefined-variable audit for deliverables (plans/deliverables.md
+ * Phase 1): preserve-parse every source markdown file, collect the
+ * variables referenced by `{{ … }}` / `{% if … %}` / inline spans, and
+ * report any not defined by the deliverable's merged attribute context.
+ * A `{% if distro == "rosa" %}` whose variable NO deliverable defines is
+ * almost certainly a typo — and invisible at build time, because the
+ * terminal build treats undefined conditions as falsy and silently drops
+ * the block.
+ *
+ * Command-side helper (does I/O); the result is surfaced through a
+ * registered corpus rule closure so it joins the normal audit report and
+ * exit-code accounting.
+ */
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { dogsbayMdToTree } from "@dogsbay/format-dogsbay-md";
+/** Words that appear in expressions but are never variables. */
+const EXPR_RESERVED = new Set([
+    "true",
+    "false",
+    "null",
+    "none",
+    "and",
+    "or",
+    "not",
+    "in",
+    "is",
+    "defined",
+    "undefined",
+]);
+/**
+ * Root identifiers referenced by an expression: quoted strings and
+ * dotted property tails stripped, reserved words and numbers excluded.
+ * `platform == "win" and product.name` → {platform, product}.
+ */
+export function expressionIdentifiers(expr) {
+    const out = new Set();
+    const stripped = expr
+        .replace(/"[^"]*"|'[^']*'/g, " ")
+        .replace(/\.[A-Za-z_][A-Za-z0-9_-]*/g, "");
+    for (const m of stripped.matchAll(/[A-Za-z_][A-Za-z0-9_-]*/g)) {
+        const id = m[0];
+        if (!EXPR_RESERVED.has(id.toLowerCase()))
+            out.add(id);
+    }
+    return out;
+}
+function collectInline(nodes, acc) {
+    for (const n of nodes ?? []) {
+        const t = n.type;
+        if (t === "variable") {
+            for (const id of expressionIdentifiers(n.expr)) {
+                addRef(acc, id, "{{ … }}");
+            }
+        }
+        else if (t === "conditional-span") {
+            const span = n;
+            for (const id of expressionIdentifiers(span.test))
+                addRef(acc, id, "{% if %}");
+            collectInline(span.children, acc);
+        }
+        else {
+            const children = n.children;
+            if (children)
+                collectInline(children, acc);
+        }
+    }
+}
+function addRef(acc, id, kind) {
+    const kinds = acc.refs.get(id) ?? new Set();
+    kinds.add(kind);
+    acc.refs.set(id, kinds);
+}
+function collectBlocks(nodes, acc) {
+    for (const node of nodes) {
+        if (node.type === "conditional") {
+            for (const id of expressionIdentifiers(String(node.props?.test ?? ""))) {
+                addRef(acc, id, "{% if %}");
+            }
+        }
+        else if (node.type === "var-def") {
+            acc.defined.add(String(node.props?.name ?? ""));
+            for (const id of expressionIdentifiers(String(node.props?.value ?? ""))) {
+                addRef(acc, id, "{% set %}");
+            }
+        }
+        if (node.inline)
+            collectInline(node.inline, acc);
+        if (node.children)
+            collectBlocks(node.children, acc);
+    }
+}
+async function mdFiles(dir) {
+    const out = [];
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+        if (entry.name.startsWith(".") || entry.name === "node_modules")
+            continue;
+        const full = join(dir, entry.name);
+        if (entry.isDirectory())
+            out.push(...(await mdFiles(full)));
+        else if (entry.name.endsWith(".md"))
+            out.push(full);
+    }
+    return out;
+}
+/** hyphen/underscore-insensitive (the preprocessor runs hyphenToUnderscore). */
+const canon = (s) => s.replace(/-/g, "_");
+export async function auditDeliverableVariables(options) {
+    const known = new Set(Object.keys(options.attributes).map(canon));
+    const issues = [];
+    for (const dir of options.contentDirs) {
+        for (const file of await mdFiles(dir)) {
+            const source = await readFile(file, "utf8").catch(() => null);
+            if (source === null)
+                continue;
+            const acc = { refs: new Map(), defined: new Set() };
+            try {
+                const { tree } = dogsbayMdToTree(source, { directives: "preserve" });
+                collectBlocks(tree, acc);
+            }
+            catch {
+                continue; // unparseable file — other rules own that problem
+            }
+            for (const [id, kinds] of acc.refs) {
+                if (known.has(canon(id)))
+                    continue;
+                if ([...acc.defined].some((d) => canon(d) === canon(id)))
+                    continue;
+                issues.push({
+                    ruleId: "directives/undefined-variable",
+                    severity: "warning",
+                    file: relative(options.siteRoot, file),
+                    message: `"${id}" (used in ${[...kinds].join(", ")}) is not defined by ` +
+                        `deliverable "${options.deliverable}" — the terminal build treats ` +
+                        `undefined conditions as falsy, so guarded content is silently dropped.`,
+                });
+            }
+        }
+    }
+    return issues;
+}

package/dist/audit/rules/structure/index.d.ts

@@ -0,0 +1,2 @@
+/** Idempotent, like the shared register* functions. */
+export declare function registerCliStructureRules(): void;

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

@@ -1,37 +1,17 @@
 /**
- * Structure rule category — register all `structure/*` rules
- * into the global registry. Imported by the audit runner /
- * site-check command at startup.
- *
- * Rules landed in this category:
- *   - structure/namespace-coherence  (corpus, multi-source axis)
- *
- * Future additions:
- *   - structure/orphan-pages         (corpus; pages not reachable from nav)
- *   - structure/duplicate-slugs      (corpus; two sources produced the same URL)
+ * The Astro CLI's own structure rules, registered on top of the shared
+ * ones from `@dogsbay/site-check`. Both read nav files and topic maps
+ * from disk, which dogsbay-ssg resolves differently.
  */
-import { registerRule } from "../../registry.js";
-import { localeCoherence } from "./locale-coherence.js";
-import { namespaceCoherence } from "./namespace-coherence.js";
-import { versionCoherence } from "./version-coherence.js";
+import { registerRule } from "@dogsbay/site-check";
+import { navTargetExists } from "./nav-target-exists.js";
+import { topicmapValid } from "./topicmap-valid.js";
 let registered = false;
-/**
- * Idempotent — calling `registerStructureRules` more than once
- * is a no-op.
- */
-export function registerStructureRules() {
+/** Idempotent, like the shared register* functions. */
+export function registerCliStructureRules() {
     if (registered)
         return;
     registered = true;
-    registerRule(namespaceCoherence);
-    registerRule(versionCoherence);
-    registerRule(localeCoherence);
-}
-/**
- * Test-only: reset the "registered" flag so unit tests can
- * register fresh after `_clearRegistry()`. Production code never
- * calls this.
- */
-export function _resetStructureRegistration() {
-    registered = false;
+    registerRule(navTargetExists);
+    registerRule(topicmapValid);
 }

package/dist/audit/rules/structure/nav-target-exists.d.ts

@@ -0,0 +1,2 @@
+import type { Rule } from "@dogsbay/site-check";
+export declare const navTargetExists: Rule;

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

@@ -0,0 +1,107 @@
+/**
+ * `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}). To fix: rename the ` +
+                        `file to match, correct the path in the nav file, 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/rules/structure/topicmap-valid.d.ts

@@ -0,0 +1,12 @@
+/**
+ * structure/topicmap-valid — surfaces topic-map resolution problems
+ * (cycles, missing includes, malformed entries, variable errors) as
+ * structured audit issues.
+ *
+ * The audit runner is synchronous while topic-map resolution is async, so
+ * site-check resolves each topic-map nav BEFORE the audit run and attaches
+ * the errors to `AuditSourceInfo.topicmapErrors`; this rule just reports
+ * them with the standard exit-code/severity plumbing.
+ */
+import type { Rule } from "@dogsbay/site-check";
+export declare const topicmapValid: Rule;

package/dist/audit/rules/structure/topicmap-valid.js

@@ -0,0 +1,25 @@
+export const topicmapValid = {
+    id: "structure/topicmap-valid",
+    category: "structure",
+    stage: "source-corpus",
+    severity: "error",
+    description: "Topic-map navs (nav: *.topicmap.yml) must resolve cleanly: no cycles, missing includes, or malformed entries",
+    run(rawCtx) {
+        const ctx = rawCtx;
+        const issues = [];
+        for (const source of ctx.auditSources ?? []) {
+            if (!source.topicmapErrors)
+                continue;
+            const fallback = source.topicmapPath ?? source.navOverride ?? "(topic map)";
+            for (const error of source.topicmapErrors) {
+                issues.push({
+                    ruleId: "structure/topicmap-valid",
+                    severity: "error",
+                    file: error.mapPath || fallback,
+                    message: `[${error.code}] ${error.message}`,
+                });
+            }
+        }
+        return issues;
+    },
+};

package/dist/child-links.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Realize `::child-links` on every page against the site's nav
+ * (plans/child-links.md). Shared by `site build` (after the nav is final) and
+ * `convert --to <anything but dogsbay-md>`; Dogsbay MD keeps the directive.
+ */
+import type { ExportPage, NavItem } from "@dogsbay/types";
+export interface SiteChildLinksResult {
+    realized: number;
+    /** `page: folder` for every listing that found no child pages. */
+    empty: string[];
+    /** `page: folder` for listings answered from the page directory, not the nav. */
+    fromDirectory: string[];
+}
+/**
+ * @param prefix the href prefix the nav was built with (`""` for `convert`,
+ *   urlBase + basePath for `site build`): a page's nav href is
+ *   `prefix/slug`, and a `folder=` path is site-relative, so it is prefixed too.
+ */
+export declare function realizeSiteChildLinks(pages: ExportPage[], nav: NavItem[], prefix: string): SiteChildLinksResult;

package/dist/child-links.js

@@ -0,0 +1,48 @@
+import { directoryChildren, hasChildLinks, navKey, realizeChildLinks } from "@dogsbay/serialize-core";
+/**
+ * @param prefix the href prefix the nav was built with (`""` for `convert`,
+ *   urlBase + basePath for `site build`): a page's nav href is
+ *   `prefix/slug`, and a `folder=` path is site-relative, so it is prefixed too.
+ */
+export function realizeSiteChildLinks(pages, nav, prefix) {
+    const out = { realized: 0, empty: [], fromDirectory: [] };
+    if (!pages.some((p) => hasChildLinks(p.tree)))
+        return out;
+    const base = prefix.replace(/\/+$/, "");
+    const hrefOf = (slug) => `${base}/${slug.replace(/(^|\/)index$/, "")}`;
+    const info = new Map();
+    for (const page of pages) {
+        const { description, tags } = page.frontmatter ?? {};
+        info.set(navKey(hrefOf(page.slug)), {
+            title: page.title || undefined,
+            description: typeof description === "string" ? description : undefined,
+            tags: Array.isArray(tags) ? tags.map(String) : undefined,
+            // For `match=` (front-matter filters).
+            data: page.frontmatter,
+        });
+    }
+    // Trees carry SITE-relative links: Astro adds the base path itself, and an
+    // export target (a vault, MkDocs) has none. The nav is built with it on.
+    const outputHref = (href) => base && (href === base || href.startsWith(`${base}/`)) ? href.slice(base.length) || "/" : href;
+    let fallbackChildren;
+    for (const page of pages) {
+        if (!hasChildLinks(page.tree))
+            continue;
+        // Fragments, partials (`_`-prefixed segments) and redirect stubs are not pages to list.
+        fallbackChildren ??= directoryChildren(pages.filter((p) => !p.fragment && !p.redirect && !p.slug.split("/").some((seg) => seg.startsWith("_"))), hrefOf);
+        const r = realizeChildLinks(page.tree, {
+            nav,
+            fallbackChildren,
+            outputHref,
+            pageHref: hrefOf(page.slug),
+            folderHref: (folder) => `${base}/${folder.replace(/^\/+/, "")}`,
+            lookup: (href) => info.get(navKey(href)),
+        });
+        out.realized += r.realized;
+        for (const e of r.empty)
+            out.empty.push(`${page.slug}: ${e}`);
+        for (const e of r.fromFallback)
+            out.fromDirectory.push(`${page.slug}: ${e}`);
+    }
+    return out;
+}

package/dist/commands/add.d.ts

@@ -0,0 +1,8 @@
+import { type RegistryEntry } from "../registry.js";
+export declare function collectDependencies(names: string[]): {
+    components: RegistryEntry[];
+    npmDeps: string[];
+    primitives: Set<string>;
+};
+export declare function add(componentNames: string[]): void;
+export declare function list(): void;

package/dist/commands/add.js

@@ -22,7 +22,7 @@ function getSourceDir() {
         return monorepo;
     throw new Error("Could not find component source files.");
 }
-function collectDependencies(names) {
+export function collectDependencies(names) {
     const visited = new Set();
     const components = [];
     const npmDeps = [];

package/dist/commands/convert.d.ts

@@ -0,0 +1,64 @@
+import type { ExportPage, FormatPlugin, NavItem } from "@dogsbay/types";
+import { FORMATS as formats, detectFormat } from "../formats.js";
+export { formats, detectFormat };
+/**
+ * Conversion failure with an optional hint line (e.g. the list of
+ * available formats). `convert` (the CLI action) renders it red and
+ * exits; programmatic callers (the corpus update loop) catch it and
+ * ledger the failure instead of aborting the run.
+ */
+export declare class ConvertError extends Error {
+    hint?: string;
+    constructor(message: string, hint?: string);
+}
+/**
+ * Parse + VALIDATE a declarative components config.
+ *
+ * The components map is the only thing that overrides format-mdx's built-in
+ * strip list, so a config that fails to load silently re-enables stripping —
+ * content vanishes from the output with no error. Every way that could happen
+ * is now an error instead:
+ *
+ *   - empty / all-comment file  → parsed as null, previously fell through as
+ *     a falsy config and compilation was skipped entirely
+ *   - wrapper-key typo (`component:` for `components:`) → the old
+ *     `parsed?.components ?? parsed` fallback accepted the whole file and
+ *     registered one mapping for a tag literally named "component"
+ *   - a non-object entry, or an entry whose keys are all unrecognised
+ *
+ * Accepts either a bare mapping or a `{ components: … }` wrapper.
+ */
+export declare function parseComponentsConfig(text: string, path: string): Record<string, unknown>;
+/**
+ * Resolve the importer for a source and run it — the IMPORT half of
+ * `runConvert`, without an exporter.
+ *
+ * `dogsbay chunk` needs pages and nav but has no target format, and consumers
+ * that duplicate the plugin list drift from it (the registry is order-
+ * sensitive: gitbook and hugo must be tried before the generic dogsbay-md
+ * detector or their markup is silently skipped). One resolver, one order.
+ */
+export declare function importPages(source: string, options: {
+    from?: string;
+    [key: string]: unknown;
+}, log?: (msg: string) => void): Promise<{
+    pages: ExportPage[];
+    nav: NavItem[];
+    importer: FormatPlugin;
+}>;
+export declare function runConvert(source: string, options: {
+    from?: string;
+    to?: string;
+    output?: string;
+    [key: string]: unknown;
+}, log?: (msg: string) => void): Promise<{
+    output: string;
+    pageCount: number;
+}>;
+/** CLI action: `dogsbay convert` — renders ConvertError red and exits. */
+export declare function convert(source: string, options: {
+    from?: string;
+    to?: string;
+    output?: string;
+    [key: string]: unknown;
+}): Promise<void>;