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

package/dist/frontmatter-check.js

@@ -0,0 +1,223 @@
+/**
+ * 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 { AGGREGATOR_OWNED, WELL_KNOWN_FIELDS, contentRelativePath, isSafeAutoFix, matchesType, nearMisses, requiredFieldsFor, typeOf, } from "./frontmatter-schema.js";
+/**
+ * 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 function checkFrontmatter(frontmatter, path, policy, keyLines = new Map()) {
+    const out = [];
+    const fm = frontmatter ?? {};
+    const at = (key) => (keyLines.has(key) ? { key, line: keyLines.get(key) } : { key });
+    for (const [key, value] of Object.entries(fm)) {
+        const taxonomy = policy.taxonomies[key];
+        const spec = WELL_KNOWN_FIELDS[key];
+        if (AGGREGATOR_OWNED.includes(key))
+            continue; // reported below, once, whatever its type
+        if (!spec && !taxonomy) {
+            // an unknown-key policy applies to CONTENT only: a README or a plan in the same
+            // workspace is not a page, and reporting its keys is noise
+            if (policy.unknown !== "ignore" && contentRelativePath(policy, path) !== null) {
+                out.push({
+                    severity: policy.unknown === "error" ? "error" : "warning",
+                    code: "frontmatter-unknown",
+                    message: `unknown frontmatter key "${key}" (not a well-known field or a declared taxonomy)`,
+                    ...at(key),
+                });
+            }
+            continue;
+        }
+        if (value === null || value === undefined)
+            continue; // an empty key is a stub, not a wrong type
+        // A DECLARED taxonomy wins over the built-in field spec: taxonomy terms are strings (the
+        // collector drops anything else), so `product: 3` must be reported even though the chunker's
+        // own `product` facet would have taken a number.
+        const effective = taxonomy ? { type: "string|string[]" } : spec;
+        if (effective && !matchesType(value, effective.type)) {
+            out.push({ severity: "error", code: "frontmatter-type", message: `"${key}" should be ${effective.type}, got ${typeOf(value)}`, ...at(key) });
+            continue;
+        }
+        if (spec && !matchesType(value, spec.type)) {
+            out.push({ severity: "error", code: "frontmatter-type", message: `"${key}" should be ${spec.type}, got ${typeOf(value)}`, ...at(key) });
+            continue; // an enum check on the wrong type says nothing useful
+        }
+        // `tags: api, guides` is ONE tag called "api, guides" — the coercion wraps the scalar, it
+        // does not split it, so the writer silently gets a tag nobody will ever match
+        // ONLY where the coercion wraps rather than splits: the taxonomy/meta fields. The chunker's
+        // facet axes split a string themselves, so a comma there is fine.
+        const wrapsScalar = taxonomy !== undefined || key === "tags" || key === "audience" || key === "category";
+        if (typeof value === "string" && /,\s*\S/.test(value) && wrapsScalar) {
+            out.push({
+                severity: "warning",
+                code: "frontmatter-comma-scalar",
+                message: `"${key}: ${value}" is ONE value containing a comma, not a list — write it as a YAML list (\`[a, b]\`) if you meant several`,
+                ...at(key),
+            });
+        }
+        // a value the pipeline discards: an empty string or an empty list is not "no value", it is a
+        // value that silently disappears (parseMeta drops both)
+        if ((typeof value === "string" && value.trim() === "") || (Array.isArray(value) && value.length === 0)) {
+            out.push({
+                severity: "warning",
+                code: "frontmatter-empty",
+                message: `"${key}" is empty, so it is dropped — remove the key or give it a value`,
+                ...at(key),
+            });
+            continue;
+        }
+        // a closed set: the well-known `status`, or a taxonomy that declared `values`
+        const allowed = spec?.values ?? taxonomy?.values;
+        const terms = typeof value === "string" ? [value] : Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
+        if (allowed) {
+            for (const term of terms) {
+                const head = taxonomy?.hierarchical ? term.split("/")[0] : term;
+                if (allowed.includes(term) || (taxonomy?.hierarchical && allowed.includes(head)))
+                    continue;
+                // a hierarchical taxonomy declares its HEAD terms, so `apu/rest` is a near miss of `api`
+                const probe = taxonomy?.hierarchical ? head : term;
+                const near = nearMisses(probe, allowed);
+                // a hierarchical fix keeps the sub-term: `apu/rest` → `api/rest`, never `api`
+                const replacement = near.length === 1
+                    ? (taxonomy?.hierarchical && term !== head ? `${near[0]}${term.slice(head.length)}` : near[0])
+                    : undefined;
+                out.push({
+                    severity: "error",
+                    code: "frontmatter-enum",
+                    message: taxonomy?.hierarchical && term !== head
+                        ? `"${key}: ${term}" starts with "${head}", which is not one of ${allowed.join(", ")}`
+                        : `"${key}: ${term}" is not one of ${allowed.join(", ")}`,
+                    ...at(key),
+                    ...(near.length ? { candidates: near } : {}),
+                    // ONLY a case slip is applied with one click: at edit distance 2 the single
+                    // candidate for `unstable` is `stable`, and inverting a writer's meaning on a
+                    // click is worse than making them choose
+                    ...(replacement && typeof value === "string" && isSafeAutoFix(probe, near[0])
+                        ? { fix: { key, value: replacement, label: `Use "${replacement}"` } }
+                        : {}),
+                });
+            }
+        }
+        if (taxonomy && !taxonomy.hierarchical) {
+            for (const term of terms) {
+                if (!term.includes("/"))
+                    continue;
+                out.push({
+                    severity: "warning",
+                    code: "frontmatter-nesting",
+                    message: `"${key}: ${term}" uses slash nesting, but the ${key} taxonomy is not hierarchical — it will be one flat term`,
+                    ...at(key),
+                });
+            }
+        }
+    }
+    // the free-form `props:` bag, against the config's `propSchema`
+    const props = fm.props;
+    if (props && typeof props === "object" && !Array.isArray(props)) {
+        for (const [key, value] of Object.entries(props)) {
+            const spec = policy.propSchema[key];
+            if (!spec || value === null || value === undefined)
+                continue;
+            if (typeof value !== spec.type) {
+                out.push({ severity: "error", code: "frontmatter-prop-type", message: `"props.${key}" should be ${spec.type}, got ${typeOf(value)}`, ...at("props") });
+                continue;
+            }
+            if (spec.enum && !spec.enum.includes(String(value))) {
+                const near = nearMisses(String(value), spec.enum);
+                out.push({
+                    severity: "error",
+                    code: "frontmatter-prop-enum",
+                    message: `"props.${key}: ${String(value)}" is not one of ${spec.enum.join(", ")}`,
+                    ...at("props"),
+                    ...(near.length ? { candidates: near } : {}),
+                });
+            }
+        }
+    }
+    // keys the multi-source build writes: a writer setting one by hand routes the page wrong
+    for (const key of AGGREGATOR_OWNED) {
+        if (fm[key] === undefined)
+            continue;
+        out.push({
+            severity: "warning",
+            code: "frontmatter-aggregator-owned",
+            message: `"${key}" is written by the multi-source build, not by hand — the build overwrites it, so setting it here has no effect`,
+            ...at(key),
+        });
+    }
+    for (const field of requiredFieldsFor(policy, path)) {
+        const value = fm[field];
+        if (value === undefined || value === null || value === "") {
+            out.push({
+                severity: "error",
+                code: "frontmatter-required",
+                message: `"${field}" is required here but is ${value === undefined ? "missing" : "empty"}`,
+                ...at(field),
+            });
+        }
+    }
+    return out;
+}
+/**
+ * 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 function frontmatterPolicyFromConfig(cfg, roots) {
+    const out = { taxonomies: {}, propSchema: {}, required: [], unknown: "ignore", roots };
+    if (!cfg || typeof cfg !== "object")
+        return out;
+    const taxonomies = (cfg.taxonomies ?? {});
+    for (const [field, raw] of Object.entries(taxonomies)) {
+        if (!raw || typeof raw !== "object")
+            continue;
+        const rec = raw;
+        out.taxonomies[field] = {
+            values: Array.isArray(rec.values) ? rec.values.filter((v) => typeof v === "string") : undefined,
+            hierarchical: rec.hierarchical === true,
+        };
+    }
+    // `propSchema` shorthand is a bare type name; the long form adds an enum
+    const propSchema = (cfg.propSchema ?? {});
+    for (const [key, raw] of Object.entries(propSchema)) {
+        if (typeof raw === "string" && ["string", "number", "boolean"].includes(raw)) {
+            out.propSchema[key] = { type: raw };
+        }
+        else if (raw && typeof raw === "object") {
+            const rec = raw;
+            if (typeof rec.type === "string" && ["string", "number", "boolean"].includes(rec.type)) {
+                out.propSchema[key] = {
+                    type: rec.type,
+                    enum: Array.isArray(rec.enum) ? rec.enum.map((v) => String(v)) : undefined,
+                };
+            }
+        }
+    }
+    const content = (cfg.content ?? {});
+    const fm = (content.frontmatter ?? {});
+    if (fm.unknown === "warn" || fm.unknown === "error")
+        out.unknown = fm.unknown;
+    else if (fm.unknown !== undefined && fm.unknown !== "ignore") {
+        // the CLI throws on this; the IDE reads the config directly, so say so rather than
+        // silently applying no policy at all
+        out.invalid = `content.frontmatter.unknown must be "ignore" | "warn" | "error"; got ${JSON.stringify(fm.unknown)}`;
+    }
+    const required = fm.required;
+    if (required && typeof required === "object") {
+        for (const [glob, fields] of Object.entries(required)) {
+            const list = Array.isArray(fields) ? fields.filter((f) => typeof f === "string") : typeof fields === "string" ? [fields] : [];
+            if (list.length)
+                out.required.push({ glob, fields: list });
+        }
+    }
+    return out;
+}

package/dist/frontmatter-schema.d.ts

@@ -0,0 +1,96 @@
+/** The YAML shapes a field may take. `date` accepts a Date (js-yaml parses ISO dates) or an ISO-ish string. */
+export type FieldType = "string" | "number" | "boolean" | "date" | "string[]" | "string|string[]" | "object" | "boolean|object" | "scalar|scalar[]";
+export interface FieldSpec {
+    type: FieldType;
+    /** Closed set of values (checked case-sensitively; a case-only miss is reported with the fix). */
+    values?: string[];
+}
+/**
+ * The well-known fields. Anything not listed is free-form as far as the
+ * engine is concerned (see `unknown` above).
+ */
+export declare const WELL_KNOWN_FIELDS: Record<string, FieldSpec>;
+/**
+ * Fields the pipeline ACCEPTS but does not act on: they are here so imported
+ * content does not light up as "unknown", not because setting them does
+ * anything. Kept in one list so the docs can say so honestly.
+ */
+export declare const INERT_FIELDS: Set<string>;
+/**
+ * Keys the AGGREGATOR owns: the multi-source build writes them, and a writer
+ * setting one by hand is a mistake that shows up as a page routed to the
+ * wrong namespace/version (documented in the frontmatter-fields skill).
+ */
+export declare const AGGREGATOR_OWNED: string[];
+/** One `propSchema` entry from dogsbay.config: a type, optionally a closed set. */
+export interface PropSpec {
+    type: "string" | "number" | "boolean";
+    enum?: string[];
+}
+export interface TaxonomySpec {
+    values?: string[];
+    hierarchical?: boolean;
+}
+export interface FrontmatterPolicy {
+    /** Declared taxonomies (config `taxonomies:`), keyed by frontmatter field name. */
+    taxonomies: Record<string, TaxonomySpec>;
+    /**
+     * Config `propSchema:` — the free-form `props:` bag's declared shape. It has
+     * been in the config schema (and validated as CONFIG) since taxonomies
+     * landed, with nothing ever checking a PAGE against it.
+     */
+    propSchema: Record<string, PropSpec>;
+    /** `content.frontmatter.required`: path glob → fields that must be present. */
+    required: Array<{
+        glob: string;
+        fields: string[];
+    }>;
+    /** `content.frontmatter.unknown`: what to do with keys nobody declared. */
+    unknown: "ignore" | "warn" | "error";
+    /**
+     * The content roots (config `content.sources[].path`). The declared policy
+     * applies to CONTENT: a README, a plan or a dev note in the same workspace
+     * is not a page, and reporting its frontmatter is noise. Globs are matched
+     * against the content-root-relative path, which is what a writer means by
+     * `guides/**`.
+     */
+    roots: string[];
+    /** Set when the config's policy is itself malformed — reported, never guessed around. */
+    invalid?: string;
+}
+export declare const EMPTY_POLICY: FrontmatterPolicy;
+/** The type name to SHOW for a value the writer got wrong. */
+export declare const typeOf: (v: unknown) => string;
+export declare function matchesType(value: unknown, type: FieldType): boolean;
+/**
+ * The near-miss values for a bad enum entry: a case-only difference first
+ * (the overwhelmingly common typo), then a one-edit neighbour. A fix is
+ * offered only when exactly one candidate comes back.
+ */
+export declare function nearMisses(value: string, allowed: string[]): string[];
+/**
+ * Whether a near miss may be APPLIED with one click, as opposed to merely
+ * listed. Only a case difference qualifies: at edit distance 2 the single
+ * candidate for `unstable` is `stable`, and for `review` it is `preview` —
+ * a one-click fix that inverts the writer's meaning is worse than no fix.
+ */
+export declare const isSafeAutoFix: (value: string, candidate: string) => boolean;
+/**
+ * The 1-based line of a top-level key inside the frontmatter block, so a
+ * finding can be revealed where the writer wrote it. Only the block is
+ * scanned (the body may contain a line that looks like a key).
+ */
+export declare function frontmatterKeyLines(source: string): Map<string, number>;
+/**
+ * `content/guides/**` / `*.md` / `content/*​/index.md`. Deliberately small:
+ * `**` crosses directories, `*` does not, everything else is literal.
+ */
+export declare function globMatches(glob: string, path: string): boolean;
+/**
+ * The path a glob is matched against: relative to the content root the doc
+ * lives under, so `guides/**` means what the writer means when their content
+ * is `content/guides/…`. A doc outside every declared root is not content.
+ */
+export declare function contentRelativePath(policy: FrontmatterPolicy, path: string): string | null;
+/** Fields required for a path by the declared globs (deduped, in declaration order). */
+export declare function requiredFieldsFor(policy: FrontmatterPolicy, path: string): string[];

package/dist/frontmatter-schema.js

@@ -0,0 +1,243 @@
+/**
+ * What page frontmatter MEANS — the vocabulary `validate` and `site check`
+ * (through `checkFrontmatter`, frontmatter-check.ts) check against
+ * (plans/frontmatter-validation.md).
+ *
+ * Three sources, in order of how much the writer had to declare:
+ *
+ *  1. WELL-KNOWN FIELDS. `docs/metadata.md` is the field reference and the
+ *     emitters read exactly these; the table below mirrors it. A bare
+ *     directory with no config gets type checking for free.
+ *  2. `taxonomies:` in `dogsbay.config.*` — already carries `values` (the
+ *     allowed terms) and `hierarchical` (whether `api/rest` is legal). No
+ *     new config surface: if you declared the taxonomy, you declared the
+ *     check.
+ *  3. `content.frontmatter` — opt-in strictness: `required` (globs → fields
+ *     that must be present) and `unknown` (ignore | warn | error).
+ *
+ * Unknown keys are silent unless (3) asks for them: free-form keys are
+ * legitimate, and a checker that cries wolf on them gets switched off.
+ *
+ * The nine fields `parseMeta` owns are checked against the rules IT applies
+ * (it silently drops what it cannot use), and `tests/meta-parity.test.ts`
+ * asserts the two agree value-by-value — the anti-drift device, since a
+ * checker that disagrees with the parser is worse than no checker.
+ */
+import { STATUS_VALUES } from "./meta.js";
+/**
+ * The well-known fields. Anything not listed is free-form as far as the
+ * engine is concerned (see `unknown` above).
+ */
+export const WELL_KNOWN_FIELDS = {
+    title: { type: "string" },
+    description: { type: "string" },
+    // parseMeta coerces a single string ("tags: api"), so a scalar is correct authoring
+    tags: { type: "string|string[]" },
+    category: { type: "string|string[]" },
+    type: { type: "string" },
+    status: { type: "string", values: [...STATUS_VALUES] },
+    audience: { type: "string|string[]" },
+    weight: { type: "number" },
+    updated: { type: "date" },
+    created: { type: "date" },
+    lastUpdated: { type: "date" },
+    lastmod: { type: "date" },
+    date: { type: "date" },
+    props: { type: "object" },
+    keyword: { type: "string" },
+    targetKeyword: { type: "string" },
+    // visibility / build behaviour the emitters read
+    draft: { type: "boolean" },
+    noindex: { type: "boolean" },
+    nofollow: { type: "boolean" },
+    excludeFromSearch: { type: "boolean" },
+    pagefindExclude: { type: "boolean" },
+    ogImage: { type: "string" },
+    ogType: { type: "string" },
+    canonicalUrl: { type: "string" },
+    slug: { type: "string" },
+    // every reader casts/checks `redirect` as a STRING: a list would validate and then be ignored
+    redirect: { type: "string" },
+    // Old paths that should forward TO this page. A list, unlike `redirect`,
+    // because a page accumulates former URLs and they are deleted with it.
+    aliases: { type: "string[]" },
+    llmActions: { type: "boolean|object" },
+    preprocess: { type: "boolean" },
+    autoH1: { type: "boolean" },
+    autoLede: { type: "boolean" },
+    fragment: { type: "boolean" },
+    _fragment: { type: "boolean" },
+    "single-page": { type: "string", values: ["yes", "children", "no"] },
+    // chunk facet keys (@dogsbay/chunk facets.ts TAXONOMY_KEYS) — consumed even without a
+    // `taxonomies:` declaration, so reporting them as unknown would be a false positive
+    product: { type: "scalar|scalar[]" },
+    platform: { type: "scalar|scalar[]" },
+    edition: { type: "scalar|scalar[]" },
+    // DITA profiling attributes carried through the pipeline
+    rev: { type: "scalar|scalar[]" },
+    otherprops: { type: "scalar|scalar[]" },
+    // stamped by the single-page (book) emitter on the pages it generates
+    granularity: { type: "string" },
+};
+/**
+ * Fields the pipeline ACCEPTS but does not act on: they are here so imported
+ * content does not light up as "unknown", not because setting them does
+ * anything. Kept in one list so the docs can say so honestly.
+ */
+export const INERT_FIELDS = new Set(["ogType", "autoH1", "autoLede", "date", "fragment", "_fragment", "slug"]);
+/**
+ * Keys the AGGREGATOR owns: the multi-source build writes them, and a writer
+ * setting one by hand is a mistake that shows up as a page routed to the
+ * wrong namespace/version (documented in the frontmatter-fields skill).
+ */
+export const AGGREGATOR_OWNED = ["multiSource"];
+export const EMPTY_POLICY = { taxonomies: {}, propSchema: {}, required: [], unknown: "ignore", roots: [""] };
+/* ───────────────────────────── type checking ───────────────────────────── */
+// `2026`, `2026-08` and RFC-1123 are all valid to the consumers (sitemap lastmod, `new Date()`),
+// so the check is "a date this system can read", not one spelling of it
+const isDateString = (v) => /^\d{4}(-\d{2}(-\d{2}([T ].*)?)?)?$/.test(v.trim()) || !Number.isNaN(Date.parse(v));
+const isStringArray = (v) => Array.isArray(v) && v.every((x) => typeof x === "string");
+/** The type name to SHOW for a value the writer got wrong. */
+export const typeOf = (v) => {
+    if (v === null)
+        return "null";
+    if (typeof v === "number" && !Number.isFinite(v))
+        return Number.isNaN(v) ? "NaN" : "infinity";
+    if (Array.isArray(v))
+        return v.every((x) => typeof x === "string") ? "string[]" : "list";
+    if (v instanceof Date)
+        return "date";
+    return typeof v;
+};
+export function matchesType(value, type) {
+    switch (type) {
+        case "string": return typeof value === "string";
+        case "number": return typeof value === "number" && Number.isFinite(value);
+        case "boolean": return typeof value === "boolean";
+        // js-yaml turns an unquoted ISO date into a Date; a quoted one stays a string
+        case "date": return value instanceof Date || (typeof value === "string" && isDateString(value));
+        case "string[]": return isStringArray(value);
+        case "string|string[]": return typeof value === "string" || isStringArray(value);
+        case "object": return typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Date);
+        case "boolean|object": return typeof value === "boolean" || (typeof value === "object" && value !== null && !Array.isArray(value));
+        // the facet/profiling axes: the chunker stringifies scalars and splits a string on
+        // whitespace/commas, so `rev: 2` and `product: a, b` are both real authoring
+        case "scalar|scalar[]": {
+            const scalar = (v) => v !== null && typeof v !== "object";
+            return scalar(value) || (Array.isArray(value) && value.every(scalar));
+        }
+    }
+}
+/**
+ * The near-miss values for a bad enum entry: a case-only difference first
+ * (the overwhelmingly common typo), then a one-edit neighbour. A fix is
+ * offered only when exactly one candidate comes back.
+ */
+export function nearMisses(value, allowed) {
+    const lower = value.toLowerCase().trim();
+    const caseOnly = allowed.filter((a) => a.toLowerCase() === lower);
+    if (caseOnly.length)
+        return caseOnly;
+    return allowed.filter((a) => editDistanceAtMost(a.toLowerCase(), lower, 2));
+}
+/**
+ * Whether a near miss may be APPLIED with one click, as opposed to merely
+ * listed. Only a case difference qualifies: at edit distance 2 the single
+ * candidate for `unstable` is `stable`, and for `review` it is `preview` —
+ * a one-click fix that inverts the writer's meaning is worse than no fix.
+ */
+export const isSafeAutoFix = (value, candidate) => value.trim().toLowerCase() === candidate.toLowerCase();
+/** Bounded Levenshtein: true when `a` and `b` are within `max` edits. */
+function editDistanceAtMost(a, b, max) {
+    if (Math.abs(a.length - b.length) > max)
+        return false;
+    let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const row = [i];
+        let best = i;
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            const v = Math.min(prev[j] + 1, row[j - 1] + 1, prev[j - 1] + cost);
+            row.push(v);
+            best = Math.min(best, v);
+        }
+        if (best > max)
+            return false;
+        prev = row;
+    }
+    return prev[b.length] <= max;
+}
+/* ───────────────────────────── key positions ───────────────────────────── */
+/**
+ * The 1-based line of a top-level key inside the frontmatter block, so a
+ * finding can be revealed where the writer wrote it. Only the block is
+ * scanned (the body may contain a line that looks like a key).
+ */
+export function frontmatterKeyLines(source) {
+    const out = new Map();
+    const lines = source.split("\n");
+    if (lines[0]?.trim() !== "---")
+        return out;
+    for (let i = 1; i < lines.length; i++) {
+        const line = lines[i];
+        // the closer is at COLUMN 0 (what splitFrontmatter matches) — an indented `---` inside a
+        // block scalar is content, and breaking on it lost the line of every key after it
+        if (/^(---|\.\.\.)[ \t]*\r?$/.test(line))
+            break;
+        const m = /^(?:"([^"]+)"|'([^']+)'|([A-Za-z_][\w.-]*))\s*:/.exec(line); // top level only: no leading space
+        const key = m?.[1] ?? m?.[2] ?? m?.[3];
+        if (key && !out.has(key))
+            out.set(key, i + 1);
+    }
+    return out;
+}
+/* ─────────────────────────────── globs ─────────────────────────────────── */
+/**
+ * `content/guides/**` / `*.md` / `content/*​/index.md`. Deliberately small:
+ * `**` crosses directories, `*` does not, everything else is literal.
+ */
+export function globMatches(glob, path) {
+    const escaped = glob
+        .split("**")
+        .map((part) => part.split("*").map((lit) => lit.replace(/[.+^${}()|[\]\\?]/g, "\\$&")).join("[^/]*"))
+        .join(".*");
+    return new RegExp(`^${escaped}$`).test(path);
+}
+/**
+ * The path a glob is matched against: relative to the content root the doc
+ * lives under, so `guides/**` means what the writer means when their content
+ * is `content/guides/…`. A doc outside every declared root is not content.
+ */
+export function contentRelativePath(policy, path) {
+    const roots = policy.roots.length ? policy.roots : [""];
+    let best = null;
+    for (const root of roots) {
+        if (root === "") {
+            if (best === null)
+                best = path;
+            continue;
+        }
+        const prefix = root.replace(/\/+$/, "") + "/";
+        if (path.startsWith(prefix)) {
+            const rel = path.slice(prefix.length);
+            if (best === null || rel.length < best.length)
+                best = rel;
+        }
+    }
+    return best;
+}
+/** Fields required for a path by the declared globs (deduped, in declaration order). */
+export function requiredFieldsFor(policy, path) {
+    const rel = contentRelativePath(policy, path);
+    if (rel === null)
+        return [];
+    const out = [];
+    for (const rule of policy.required) {
+        if (!globMatches(rule.glob, rel))
+            continue;
+        for (const f of rule.fields)
+            if (!out.includes(f))
+                out.push(f);
+    }
+    return out;
+}

package/dist/index.d.ts

@@ -1,8 +1,13 @@
-export type { TreeNode, InlineNode, InlineText, InlineLink, InlineImage, InlineCode, InlineFootnoteRef, InlineKbd, InlineIcon, InlineMath, InlineHtml, InlineBreak } from "./tree.js";
+export type { TreeNode, InlineNode, InlineText, InlineLink, InlineAttrs, InlineImage, InlineCode, InlineFootnoteRef, InlineKbd, InlineIcon, InlineBadge, InlineMath, InlineHtml, InlineBreak } from "./tree.js";
+export type { ConditionalNode, IncludeNode, VarDefNode, DirectiveRawNode, DirectiveBlockNode, InlineVariable, InlineConditionalSpan, InlineDirectiveRaw, InlineDirectiveNode, InlineNodeWithDirectives, ProfilingAttr, } from "./directives.js";
+export { isConditional, isInclude, isVarDef, isDirectiveRaw, isDirectiveBlock, isInlineDirective, PROFILING_ATTRS, profilingOf, } from "./directives.js";
 export { treeToJson, chunkByHeadings, extractText } from "./json.js";
 export type { RagChunk } from "./json.js";
-export type { ExportPage, Heading, NavItem, FormatPlugin, FormatOption, SiteConfig, PlausibleConfig, TagPrefixDisplay, TagPaletteName, TaxonomyDisplay, LlmActionsConfig, LlmActionsPlacement, LlmProviderName } from "./format.js";
+export type { ExportPage, Heading, NavItem, NavMark, NavMarkKind, FormatPlugin, FormatCapability, FormatOption, ImportResult, ImportLedgerEntry, SiteConfig, PlausibleConfig, TagPrefixDisplay, TagPaletteName, TaxonomyDisplay, LlmActionsConfig, LlmActionsPlacement, LlmProviderName, LinkIconsConfig } from "./format.js";
 export type { PageMeta, PageStatus, ParseMetaOptions } from "./meta.js";
-export { parseMeta } from "./meta.js";
+export { STATUS_VALUES, parseMeta } from "./meta.js";
 export type { DogsbayPlugin, DogsbayPluginContext, DogsbayPluginFactory, PluginVisibleConfig, PluginLogger, PluginRule, PluginIssue, PluginConfigEntry, EmitFilesHelpers, AstroIntegrationRef, } from "./plugin.js";
-//# sourceMappingURL=index.d.ts.map
+export { WELL_KNOWN_FIELDS, INERT_FIELDS, AGGREGATOR_OWNED, EMPTY_POLICY, typeOf, matchesType, nearMisses, isSafeAutoFix, frontmatterKeyLines, globMatches, contentRelativePath, requiredFieldsFor, } from "./frontmatter-schema.js";
+export type { FieldType, FieldSpec, PropSpec, TaxonomySpec, FrontmatterPolicy } from "./frontmatter-schema.js";
+export { checkFrontmatter, frontmatterPolicyFromConfig } from "./frontmatter-check.js";
+export type { FrontmatterFinding } from "./frontmatter-check.js";

package/dist/index.js

@@ -1,3 +1,5 @@
+export { isConditional, isInclude, isVarDef, isDirectiveRaw, isDirectiveBlock, isInlineDirective, PROFILING_ATTRS, profilingOf, } from "./directives.js";
 export { treeToJson, chunkByHeadings, extractText } from "./json.js";
-export { parseMeta } from "./meta.js";
-//# sourceMappingURL=index.js.map
+export { STATUS_VALUES, parseMeta } from "./meta.js";
+export { WELL_KNOWN_FIELDS, INERT_FIELDS, AGGREGATOR_OWNED, EMPTY_POLICY, typeOf, matchesType, nearMisses, isSafeAutoFix, frontmatterKeyLines, globMatches, contentRelativePath, requiredFieldsFor, } from "./frontmatter-schema.js";
+export { checkFrontmatter, frontmatterPolicyFromConfig } from "./frontmatter-check.js";

package/dist/json.d.ts

@@ -23,4 +23,3 @@ export declare function chunkByHeadings(nodes: TreeNode[], maxLevel?: number): R
  * Extract plain text from a TreeNode, stripping any markup.
  */
 export declare function extractText(node: TreeNode): string;
-//# sourceMappingURL=json.d.ts.map

package/dist/json.js

@@ -85,4 +85,3 @@ export function extractText(node) {
 function stripHtml(html) {
     return html.replace(/<[^>]+>/g, "").trim();
 }
-//# sourceMappingURL=json.js.map

package/dist/meta.d.ts

@@ -19,13 +19,19 @@ export interface PageMeta {
     tags?: string[];
     /**
      * Broader grouping. Auto-derived from path when frontmatter
-     * doesn't supply a valid value (`content/guides/auth.md` →
-     * `["guides"]`). Override with `category: foo` or
-     * `category: [foo, bar]`.
+     * doesn't supply a valid value, emitted as **cumulative slash-
+     * paths** so each value uniquely identifies its position in the
+     * hierarchy (`content/guides/oauth/setup.md` →
+     * `["guides", "guides/oauth"]`). The bare top segment is
+     * preserved so simple queries like `category:guides` still match
+     * the whole subtree. Override with `category: foo` or
+     * `category: [foo, bar]` (explicit values pass through
+     * unchanged — no auto-prefix).
      *
      * No first-class "belongs nowhere" sentinel in v1: `category: []`
      * falls through to slug-derived default. See
-     * plans/metadata-and-taxonomies.md.
+     * plans/metadata-and-taxonomies.md and
+     * plans/hierarchical-facets.md.
      */
     category?: string[];
     /**
@@ -41,6 +47,16 @@ export interface PageMeta {
     /** ISO date strings. Consumers parse to Date when needed. */
     updated?: string;
     created?: string;
+    /**
+     * Post authors. Accepts a single string or a list in frontmatter;
+     * always normalized to a list here so consumers have one shape.
+     *
+     * Added for the blog capability (plans/blog-capability.md) — it was
+     * the only field a post needs that PageMeta did not already carry.
+     * Absent means "no byline", never "unknown author": the layout omits
+     * the row entirely rather than rendering a placeholder.
+     */
+    author?: string[];
     /** Sort hint for navigation/list pages. Lower weight first. */
     weight?: number;
     /**
@@ -77,6 +93,12 @@ export interface ParseMetaOptions {
      */
     taxonomyNames?: readonly string[];
 }
+/**
+ * Closed enum for status validation. Exported so the frontmatter CHECKER
+ * (packages/commands) reports exactly the values this parser drops, instead
+ * of restating the list a third time.
+ */
+export declare const STATUS_VALUES: readonly PageStatus[];
 /**
  * Parse and normalize frontmatter into `PageMeta`. Pure function;
  * no I/O. Unknown frontmatter keys are not lifted — they stay in
@@ -97,4 +119,3 @@ export interface ParseMetaOptions {
  *   `meta.taxonomies` as string arrays.
  */
 export declare function parseMeta(frontmatter: Record<string, unknown> | undefined, options?: ParseMetaOptions): PageMeta;
-//# sourceMappingURL=meta.d.ts.map