@dogsbay/types 0.2.0-beta.12 → 0.2.0-beta.121

package/dist/directives.d.ts

@@ -0,0 +1,125 @@
+/**
+ * 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>>;
+//# sourceMappingURL=directives.d.ts.map

package/dist/directives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directives.d.ts","sourceRoot":"","sources":["../src/directives.ts"],"names":[],"mappings":"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"}

package/dist/directives.js

@@ -0,0 +1,27 @@
+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;
+}
+//# sourceMappingURL=directives.js.map

package/dist/directives.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"directives.js","sourceRoot":"","sources":["../src/directives.ts"],"names":[],"mappings":"AAyEA,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAW,EAAwB,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,aAAa,CAAC;AAC7F,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAW,EAAoB,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC;AACjF,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,CAAW,EAAmB,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC;AAC/E,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAW,EAAyB,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,eAAe,CAAC;AACjG,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAW,EAA2B,EAAE,CACvE,aAAa,CAAC,CAAC,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,IAAI,cAAc,CAAC,CAAC,CAAC,CAAC;AAsDvE,MAAM,sBAAsB,GAAG,IAAI,GAAG,CAAC;IACrC,UAAU;IACV,kBAAkB;IAClB,sBAAsB;CACvB,CAAC,CAAC;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAA2B,EAA4B,EAAE,CACzF,sBAAsB,CAAC,GAAG,CAAE,CAAsB,CAAC,IAAI,CAAC,CAAC;AAE3D;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,YAAY,CAAU,CAAC;AAGjG,oEAAoE;AACpE,MAAM,UAAU,WAAW,CAAC,IAAc;IACxC,MAAM,GAAG,GAA4C,EAAE,CAAC;IACxD,KAAK,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;QAClC,IAAI,IAAI,CAAC,KAAK,IAAI,GAAG,IAAI,IAAI,CAAC,KAAK;YAAE,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClE,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

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,13 +195,90 @@ 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>;
 }
+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>;
+}
 export interface FormatOption {
     flags: string;
     description: string;
@@ -157,6 +315,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 +357,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 +388,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 +441,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 +524,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

package/dist/format.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"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"}

package/dist/frontmatter-check.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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;
+//# sourceMappingURL=frontmatter-check.d.ts.map

package/dist/frontmatter-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter-check.d.ts","sourceRoot":"","sources":["../src/frontmatter-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EASL,KAAK,iBAAiB,EAEvB,MAAM,yBAAyB,CAAC;AAEjC,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,2FAA2F;IAC3F,GAAG,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CACrD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAChD,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,iBAAiB,EACzB,QAAQ,GAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAa,GACxC,kBAAkB,EAAE,CAsJtB;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,iBAAiB,CA2C/H"}