@dogsbay/types 0.2.0-beta.13 → 0.2.0-beta.131

package/dist/directives.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Directive nodes — source-level DITA/Jinja authoring constructs.
+ *
+ * ── Corpus survey (2026-07-06) ────────────────────────────────────────
+ * The authoritative directive vocabulary is @dogsbay/minja's AST
+ * (packages/minja/src/types.ts):
+ *   - variable   `{{ name }}`             → VariableNode { name }
+ *   - if/elif/else `{% if expr %}…`       → IfNode { condition, trueBranch, elif[], else }
+ *   - include    `{% include "path" %}`   → IncludeNode { path }
+ *   - set        `{% set name = expr %}`  → SetNode { name, value }
+ *   - switch / leveloffset / comment      → richer forms
+ * AsciiDoc `ifdef`/`ifndef` convert to minja `if` (adoc2md-modular);
+ * DITA conref/keyref map to includes/variables (format-dita). Profiling
+ * attributes (`@platform`/`@audience`) are plain node `props`, filtered
+ * at build via ditaval — no new node type needed.
+ *
+ * ── Why these types exist ─────────────────────────────────────────────
+ * Today these constructs are resolved to a STRING before TreeNode exists
+ * (standalone minja; see docs-dev/editor-framework-decision.md). TreeNode
+ * is the resolved-output model and has no representation of them. The
+ * editor edits the *unresolved source*, so it needs them as first-class,
+ * round-trippable nodes. The definitions below are ADDITIVE:
+ *   - block directives ride TreeNode's open `type: string` — NO union change;
+ *   - inline directives extend InlineNode via `InlineNodeWithDirectives`
+ *     (below) rather than the base union, so the monorepo's ~10 exhaustive
+ *     InlineNode consumers keep compiling. Folding them into the base
+ *     union and updating those consumers is Phase 2 — see
+ *     plans/editor-directive-model.md.
+ *
+ * ── Fidelity rule ─────────────────────────────────────────────────────
+ * Anything not modeled first-class (elif/else chains, switch, leveloffset,
+ * unknown directives) is preserved verbatim as a `directive-raw` node — a
+ * source-of-truth tool must never drop a construct it cannot fully model.
+ */
+import type { TreeNode, InlineNode } from "./tree.js";
+/** `{% if test %} … {% endif %}` — guarded flow content. elif/else: Phase 2. */
+export interface ConditionalNode extends TreeNode {
+    type: "conditional";
+    /** raw expression source, e.g. `platform == "mac"` */
+    props: {
+        test: string;
+    };
+    children: TreeNode[];
+}
+/** `{% include "src" %}` — transclusion of another topic/fragment. */
+export interface IncludeNode extends TreeNode {
+    type: "include";
+    /** `src` is the include target as written; extra keys pass through */
+    props: {
+        src: string;
+        [key: string]: unknown;
+    };
+}
+/** `{% set name = value %}` — in-document variable definition. */
+export interface VarDefNode extends TreeNode {
+    type: "var-def";
+    /** `value` is the raw value-expression source */
+    props: {
+        name: string;
+        value: string;
+    };
+}
+/** Any directive not modeled first-class, preserved verbatim for round-trip. */
+export interface DirectiveRawNode extends TreeNode {
+    type: "directive-raw";
+    /** `source` is the exact span; `kind` is a best-effort hint (e.g. "switch") */
+    props: {
+        source: string;
+        kind?: string;
+    };
+}
+export type DirectiveBlockNode = ConditionalNode | IncludeNode | VarDefNode | DirectiveRawNode;
+export declare const isConditional: (n: TreeNode) => n is ConditionalNode;
+export declare const isInclude: (n: TreeNode) => n is IncludeNode;
+export declare const isVarDef: (n: TreeNode) => n is VarDefNode;
+export declare const isDirectiveRaw: (n: TreeNode) => n is DirectiveRawNode;
+export declare const isDirectiveBlock: (n: TreeNode) => n is DirectiveBlockNode;
+/**
+ * Inline `{{ expr }}` — a variable/expression chip.
+ *
+ * The optional flags mirror InlineText's flat formatting annotations:
+ * a directive inside `**…**` carries its containing span's formatting
+ * (there is no wrapper node in the flat inline model to carry it).
+ */
+export interface InlineVariable {
+    type: "variable";
+    /** raw source between the braces, e.g. `product.name` */
+    expr: string;
+    bold?: boolean;
+    italic?: boolean;
+    strikethrough?: boolean;
+}
+/** Inline conditional span: content shown only when `test` holds. */
+export interface InlineConditionalSpan {
+    type: "conditional-span";
+    /** raw expression source */
+    test: string;
+    children: InlineNode[];
+    bold?: boolean;
+    italic?: boolean;
+    strikethrough?: boolean;
+}
+/** Inline directive not modeled first-class, preserved verbatim. */
+export interface InlineDirectiveRaw {
+    type: "directive-raw-inline";
+    /** exact source span */
+    source: string;
+    bold?: boolean;
+    italic?: boolean;
+    strikethrough?: boolean;
+}
+export type InlineDirectiveNode = InlineVariable | InlineConditionalSpan | InlineDirectiveRaw;
+/**
+ * InlineNode extended with directive members. Directive-aware code (the
+ * editor, the preserve-mode parser) uses this; the base `InlineNode` union
+ * stays unchanged so existing exhaustive consumers keep compiling. Phase 2
+ * folds these into the base union and updates those consumers.
+ */
+export type InlineNodeWithDirectives = InlineNode | InlineDirectiveNode;
+export declare const isInlineDirective: (n: InlineNodeWithDirectives) => n is InlineDirectiveNode;
+export declare const PROFILING_ATTRS: readonly ["platform", "product", "audience", "rev", "otherprops"];
+export type ProfilingAttr = (typeof PROFILING_ATTRS)[number];
+/** Extract the profiling attributes present on a node's `props`. */
+export declare function profilingOf(node: TreeNode): Partial<Record<ProfilingAttr, unknown>>;

package/dist/directives.js

@@ -0,0 +1,26 @@
+export const isConditional = (n) => n.type === "conditional";
+export const isInclude = (n) => n.type === "include";
+export const isVarDef = (n) => n.type === "var-def";
+export const isDirectiveRaw = (n) => n.type === "directive-raw";
+export const isDirectiveBlock = (n) => isConditional(n) || isInclude(n) || isVarDef(n) || isDirectiveRaw(n);
+const INLINE_DIRECTIVE_TYPES = new Set([
+    "variable",
+    "conditional-span",
+    "directive-raw-inline",
+]);
+export const isInlineDirective = (n) => INLINE_DIRECTIVE_TYPES.has(n.type);
+/* ───────────────────── profiling attributes ───────────────────────────
+ * DITA-style profiling — the *attribute* form of a conditional (the
+ * *wrapper* form is ConditionalNode). Lives in plain `props`, filtered at
+ * build via ditaval. A reserved-key convention, not a type change.
+ */
+export const PROFILING_ATTRS = ["platform", "product", "audience", "rev", "otherprops"];
+/** Extract the profiling attributes present on a node's `props`. */
+export function profilingOf(node) {
+    const out = {};
+    for (const key of PROFILING_ATTRS) {
+        if (node.props && key in node.props)
+            out[key] = node.props[key];
+    }
+    return out;
+}

package/dist/format.d.ts

@@ -16,6 +16,14 @@ export interface Heading {
 export interface ExportPage {
     /** File path relative to docs root, e.g. "getting-started" or "guides/install" */
     slug: string;
+    /**
+     * The source file, relative to the content root (`agent/index.md`), for an
+     * importer whose pages keep the author's relative links. Relative links are
+     * written against the FILE, and a directory's `index.md` has the directory
+     * as its slug, so the slug alone cannot say where `./overview` points.
+     * Importers that rewrite links to root-absolute leave it unset.
+     */
+    sourcePath?: string;
     /** Page title */
     title: string;
     /** Page content as TreeNode[] */
@@ -24,6 +32,26 @@ export interface ExportPage {
     headings: Heading[];
     /** Target URL for redirect/navigation pages (no body content, just a link) */
     redirect?: string;
+    /**
+     * Marks an include fragment (not a routable page): content meant to be
+     * `{% include %}`'d into other pages. Exporters write it as a plain `.md`
+     * include target at its slug — no frontmatter, no title, no nav entry. Used
+     * by structural-partial import modes (Docusaurus `--partial-mode include`,
+     * AsciiDoc fragments).
+     */
+    fragment?: boolean;
+    /**
+     * The page uses template-page syntax (plans/page-templates.md): Dogsbay-MD
+     * writes `template: jinja` in its front matter so the build renders it as
+     * a template page. Set by importers converting partials with parameters.
+     */
+    template?: boolean;
+    /**
+     * A template partial's declared parameters (`name`, or `name?` when
+     * optional). Dogsbay-MD writes them as front matter `params:` on the
+     * fragment, and the build validates every include against them.
+     */
+    templateParams?: string[];
     /**
      * Raw frontmatter data from the source page. Includes all YAML fields that
      * were present in the original source (title, description, tags, custom
@@ -60,6 +88,26 @@ export interface ExportPage {
      * See plans/multi-source-content.md.
      */
     multiSource?: MultiSourceMeta;
+    /**
+     * Direct-from-source markdown body, when the importer can produce
+     * one. Bypasses the TreeNode round-trip for callers that want to
+     * preserve the source's line structure verbatim (most importantly,
+     * `migrate-asciidoc`, which would otherwise see markdown-it fold
+     * adjacent non-blank lines into one paragraph and the
+     * format-dogsbay-md serializer flatten that paragraph onto a single
+     * line — turning every `ifdef` / `endif` block in the original
+     * `.adoc` into an unreadable wall of text).
+     *
+     * Importers that produce a faithful direct-from-source markdown
+     * (currently `format-asciidoc`) populate this field. Importers that
+     * don't (most format plugins) leave it `undefined` and consumers
+     * fall back to the TreeNode-derived body via `treeToDogsbayMd`.
+     *
+     * The TreeNode round-trip is still the canonical path for runtime
+     * rendering — `bodyMarkdown` is a migration-time convenience that
+     * doesn't change the import contract.
+     */
+    bodyMarkdown?: string;
 }
 /**
  * Per-page axis metadata. Set by the loader's aggregator when
@@ -93,6 +141,39 @@ export interface NavItem {
     label: string;
     href?: string;
     children?: NavItem[];
+    /**
+     * Granularity book view (plans/granularity-views.md). Opt-in, per nav node:
+     * - "yes"      — emit one rolled-up single page for this node's subtree.
+     * - "children" — emit a single page for each direct child (chapters); a
+     *                child may override with its own "no".
+     * - "no"       — no single page (the default when omitted).
+     */
+    singlePage?: "yes" | "no" | "children";
+    /**
+     * A state marker rendered beside the label — structured DATA, not text
+     * baked into `label`. Release comparisons use it for changed/new/removed
+     * pages; the same slot serves "new since your last visit", deprecation
+     * flags, and version badges.
+     *
+     * The renderer is responsible for making it perceivable WITHOUT colour
+     * (distinct glyph + visually-hidden text) — see SidebarNavTree.
+     *
+     * A branch may carry a marker for its SUBTREE: a collapsed group hides
+     * its children, so a change inside it must signal outward (the same
+     * visibility rule the diff renderer applies to tabs).
+     */
+    mark?: NavMark;
+}
+export type NavMarkKind = "added" | "changed" | "removed" | "moved";
+export interface NavMark {
+    kind: NavMarkKind;
+    /**
+     * Announced to assistive tech and shown on hover. Defaults to `kind`.
+     * A branch aggregating its subtree says so ("3 pages changed").
+     */
+    label?: string;
+    /** True when this marker summarizes DESCENDANTS, not the item itself. */
+    subtree?: boolean;
 }
 /**
  * Standard interface for format plugins.
@@ -114,12 +195,121 @@ export interface FormatPlugin {
     /** Format-specific CLI options for export */
     exportOptions?: FormatOption[];
     /** Import: read source format, produce pages + nav */
-    import?(source: string, opts: Record<string, unknown>): Promise<{
-        pages: ExportPage[];
-        nav: NavItem[];
-    }>;
+    import?(source: string, opts: Record<string, unknown>): Promise<ImportResult>;
     /** Export: write pages + nav to target format */
     export?(pages: ExportPage[], nav: NavItem[], output: string, opts: Record<string, unknown>): Promise<void>;
+    /**
+     * What the exporter can represent, per TreeNode type: one cell of the
+     * component × format matrix (`MATRIX_ROWS` in @dogsbay/serialize-core).
+     * Required of every exporter — the CLI's capability-matrix test fails on a
+     * missing cell. Same shape as serialize-core's `CapabilityDeclaration`.
+     */
+    capabilities?: readonly FormatCapability[];
+}
+/** One feature's support in one export format (see `FormatPlugin.capabilities`). */
+export interface FormatCapability {
+    feature: string;
+    support: "full" | "partial" | "none";
+    /** Required when support is not "full": how it degrades. */
+    note?: string;
+    rendersAs?: string;
+}
+export interface ImportResult {
+    pages: ExportPage[];
+    nav: NavItem[];
+    /**
+     * Directories whose CONTENTS should be mounted at `_assets/` in the output,
+     * so the `/_assets/…` refs importers rewrite image paths to actually
+     * resolve.
+     *
+     * An importer that knows where its media lives (a Starlight `src/assets`, a
+     * Docusaurus `static/`) declares it here. Without this the reference
+     * survives the conversion and the FILE does not — a page count, a retention
+     * score and a clean exit all look fine while every image 404s.
+     *
+     * `into` targets an `_assets/<into>` subdir; `mediaOnly` copies only media
+     * files, for the case where the mounted dir is the docs tree itself and
+     * carries co-located images.
+     */
+    assetMounts?: {
+        dir: string;
+        into?: string;
+        mediaOnly?: boolean;
+        exclude?: string[];
+        /**
+         * Public directory the mount lands in. Defaults to `_assets` — the name
+         * every IMPORTER rewrites its refs to. Hand-authored content differs: an
+         * author who has not read docs/images.md types `/images/logo.png`, so
+         * `format-dogsbay-md` also recognises `images/` and `assets/` and sets
+         * this to whichever it found. The copy must preserve the name, or the
+         * reference and the file disagree — the exact failure this field's
+         * neighbours exist to prevent.
+         */
+        root?: string;
+    }[];
+    /**
+     * Directory that page slugs are relative to, when it is NOT the path the
+     * user passed on the command line.
+     *
+     * MkDocs keeps its pages under `docs/`, Hugo under `content/`, a Docusaurus
+     * instance under its own docs dir — so a page at slug `guide/install`
+     * writing `{% include "_snippets/note.md" %}` means
+     * `<source>/docs/_snippets/note.md`, not `<source>/_snippets/note.md`.
+     * Resolving includes against the CLI argument missed every fragment in
+     * those corpora, which (since unresolved includes now fail the run) turned
+     * a working conversion into a hard error.
+     *
+     * Omit when slugs are relative to `source` itself.
+     */
+    contentRoot?: string;
+    /**
+     * SEVERAL content roots, each mounted under a slug prefix — the Antora
+     * PLAYBOOK case (#067): `docs/guides/` → `guides/`, `docs/server-admin-4.9/`
+     * → `server-admin/server-4.9/`. Fragments (partials, examples, images)
+     * under each `dir` are mirrored beneath its `prefix` so a page at
+     * `guides/deploy/x` writing `{% include "../../modules/ROOT/partials/y.md" %}`
+     * finds `<content>/guides/modules/ROOT/partials/y.md`. Takes precedence
+     * over `contentRoot` when present. `prefix` is `""` for the root mount.
+     */
+    sourceMounts?: {
+        dir: string;
+        prefix: string;
+    }[];
+    /**
+     * Antora playbook mode (#067): loaded components by NAME → root dir +
+     * slug prefix, for the engine's cross-component resource-ID
+     * resolution in fragments (pages get it via the plugin's own parse).
+     */
+    antoraComponents?: Record<string, {
+        dir: string;
+        prefix: string;
+    }>;
+    /**
+     * Attribute values the CORPUS declares (Antora playbook + component
+     * `asciidoc.attributes`, an AsciiBinder distro map, …) that the site
+     * build must resolve — a `{{ serverversion49 }}` the migrate emitted
+     * shipped as literal `{serverversion49}` because nothing wrote them into
+     * `dogsbay.config.yml` (#067 review). Migrate persists these under the
+     * user's own `--attribute` values (user wins).
+     */
+    corpusAttributes?: Record<string, unknown>;
+    /**
+     * What the import could not convert cleanly, by source file and line (the file is relative
+     * to the corpus root). A host lists these (the playground under Problems, the CLI in its
+     * summary); `MIGRATION.md` carries them too. Known loss, never silent loss.
+     */
+    ledger?: ImportLedgerEntry[];
+}
+/** One note from an import: what was not converted cleanly, and where. */
+export interface ImportLedgerEntry {
+    /** Source file, relative to the corpus root. */
+    file?: string;
+    /** 1-based line in that file, front matter included. */
+    line?: number;
+    severity: "info" | "warning";
+    /** Stable kebab-case kind, e.g. `unmapped-construct`, `slug-collision`. */
+    code: string;
+    message: string;
 }
 export interface FormatOption {
     flags: string;
@@ -157,6 +347,8 @@ export interface PlausibleConfig {
 export interface SiteConfig {
     /** Site name shown in header, page title suffixes, copyright notices. */
     siteName: string;
+    /** The line under the site name in the sidebar header (`site.tagline`). Default "Documentation". */
+    tagline?: string;
     /**
      * Canonical site URL. Required for `<link rel="canonical">`,
      * sitemap.xml entries, and absolute OG meta tags. Without it, those
@@ -197,6 +389,11 @@ export interface SiteConfig {
     editUri?: string;
     /** Footer copyright text. */
     copyright?: string;
+    /**
+     * "Powered by DogsBay" footer attribution. Defaults to true for generated
+     * sites; `poweredBy: false` in dogsbay.config.yml removes it entirely.
+     */
+    poweredBy?: boolean;
     /**
      * Brand keywords for the site, used by the
      * `seo/h1-brand-keyword` audit rule to verify that landing
@@ -223,6 +420,12 @@ export interface SiteConfig {
      * chips with prefix-keyed colors. See plans/tag-display-config.md.
      */
     tagPrefixes?: Record<string, TagPrefixDisplay>;
+    /**
+     * Color tag chips whose prefix has no color with a palette color
+     * chosen by a hash of the first segment. Sourced from
+     * `taxonomies.tags.autoColor`. See plans/tag-auto-color.md.
+     */
+    tagAutoColor?: boolean;
     /**
      * Per-tag leaf-label overrides (slug → display string). URLs and
      * taxonomy term-page paths still use the slug; only chip text
@@ -270,6 +473,30 @@ export interface SiteConfig {
      * human-facing UI cluster.
      */
     llmActions?: LlmActionsConfig;
+    /**
+     * Resolved glyphs for the internal/external link-icon affordance.
+     * When present, `DocsLayout` marks links in the prose with a small
+     * trailing icon so readers can tell internal navigation from links
+     * that leave the site. Sourced from `content.linkIcons` in
+     * `dogsbay.config.yml` and normalized by the CLI. Omitted (whole
+     * object absent) when the feature is off. Either side may be absent
+     * to show an icon for only that link kind. A core feature — not tied
+     * to any importer. See plans/link-resolution-and-icons.md.
+     */
+    linkIcons?: LinkIconsConfig;
+}
+/**
+ * Resolved glyphs for the internal/external link-icon affordance
+ * (`SiteConfig.linkIcons`). Classification is by href shape at render
+ * time: external = absolute (`http(s)://`) or protocol-relative
+ * (`//host`); internal = root/relative. An absent side shows no icon
+ * for that kind.
+ */
+export interface LinkIconsConfig {
+    /** Glyph appended after external links (e.g. "↗"). */
+    external?: string;
+    /** Glyph appended after internal links (e.g. "→"). */
+    internal?: string;
 }
 /**
  * Closed list of LLM provider deep-link targets. Each one is a
@@ -329,6 +556,27 @@ export interface TaxonomyDisplay {
     prefixes?: Record<string, TagPrefixDisplay>;
     /** Per-slug label overrides; key = full slug, value = display string. */
     labels?: Record<string, string>;
+    /**
+     * Sort weight for the facet column in the search dialog. Lower
+     * numbers appear first; unset facets sort alphabetically after
+     * any pinned ones. Use this to pin "Type" or "Audience" to the
+     * top of the sidebar even though they sort later by name.
+     */
+    order?: number;
+    /**
+     * Render this facet as a hierarchical tree in the search dialog
+     * instead of a flat checkbox list. Two render strategies depending
+     * on the value shape:
+     *  - Values containing `/` are treated as slash-encoded paths
+     *    (`concept/a11y` → `concept → a11y`). Common for tag taxonomies.
+     *  - Values without `/` derive their tree from `nav.json` document
+     *    order (the auto-`category` facet shape).
+     * Parent click auto-selects all descendant values; three-state
+     * checkboxes reflect partial selection. Off by default — set true
+     * on `category` and on slash-nested tag taxonomies.
+     * See plans/hierarchical-facets.md.
+     */
+    hierarchical?: boolean;
 }
 /**
  * Display config for one taxonomy prefix. Color is one of the
@@ -347,4 +595,3 @@ export interface TagPrefixDisplay {
  * type-narrow without importing CLI internals.
  */
 export type TagPaletteName = "blue" | "amber" | "emerald" | "violet" | "rose" | "slate";
-//# sourceMappingURL=format.d.ts.map

package/dist/format.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=format.js.map

package/dist/frontmatter-check.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The frontmatter checker: one page's frontmatter against the vocabulary in
+ * frontmatter-schema.ts and the site's policy. Pure, so every surface reports
+ * the same findings:
+ *
+ *  - `dogsbay validate` (@dogsbay/commands), which adds a one-click fix;
+ *  - the `frontmatter/valid` rule of `@dogsbay/site-check`, run by
+ *    `dogsbay site check` and `dogsbay-ssg check`.
+ */
+import { type FrontmatterPolicy } from "./frontmatter-schema.js";
+export interface FrontmatterFinding {
+    severity: "error" | "warning";
+    /** `frontmatter-type`, `frontmatter-required`, … (the codes `dogsbay validate` reports). */
+    code: string;
+    message: string;
+    /** The top-level key the finding is about, when there is one. */
+    key?: string;
+    /** 1-based line of that key, when `keyLines` has it. */
+    line?: number;
+    /** Near-miss values for a closed set. */
+    candidates?: string[];
+    /** A replacement safe to apply without asking (a case-only slip): set `key` to `value`. */
+    fix?: {
+        key: string;
+        value: string;
+        label: string;
+    };
+}
+/**
+ * Findings for one page. `path` is the page's source path as the policy's
+ * `roots` see it (the globs match its content-relative form); `keyLines`
+ * gives each key's line (`frontmatterKeyLines(source)`).
+ */
+export declare function checkFrontmatter(frontmatter: Record<string, unknown> | undefined, path: string, policy: FrontmatterPolicy, keyLines?: Map<string, number>): FrontmatterFinding[];
+/**
+ * The policy from a parsed `dogsbay.config.*` object: declared `taxonomies:`
+ * (their `values`/`hierarchical` ARE the check), `propSchema:`, and the
+ * opt-in `content.frontmatter` strictness. `roots` are the content roots
+ * (`content.sources[].path`). A malformed `content.frontmatter.unknown` sets
+ * `invalid` rather than being guessed around.
+ */
+export declare function frontmatterPolicyFromConfig(cfg: Record<string, unknown> | null | undefined, roots: string[]): FrontmatterPolicy;