@dogsbay/format-astro 0.2.0-beta.15 → 0.2.0-beta.151

package/dist/redirects.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Redirects — `redirect:` / `aliases:` frontmatter and the `redirects:` config
+ * key, turned into rules and then into whatever the deploy target can honour.
+ *
+ * See plans/redirects-and-aliases.md. Three things drove the design:
+ *
+ * 1. **`redirect:` was accepted everywhere and emitted nowhere.** The schema
+ *    took it, `ExportPage` carried it, the sitemap excluded the page and
+ *    `format-dogsbay-md` round-tripped it — and `format-astro` wrote a normal
+ *    empty page. Four consumers honouring a field is what made it look
+ *    supported. So the page skip lives here too, not just the rule.
+ *
+ * 2. **A rule's paths are SERVED paths.** Cloudflare matches the request path,
+ *    which carries the mount prefix. `/old → /new` on a site mounted at
+ *    `/blog` must be written `/blog/old → /blog/new` or it never fires.
+ *
+ * 3. **Trailing slashes decide whether a redirect costs one hop or two.**
+ *    Sites serve `/guide/auth/` (docs-dev/url-shape.md). A rule targeting
+ *    `/guide/auth` redirects to a path that itself redirects. Internal paths
+ *    are normalized to the served form.
+ *
+ * This module is pure: it does no IO, so every rule and every refusal is
+ * testable without building a site.
+ */
+/** One redirect, with its paths already resolved to served form. */
+export interface RedirectRule {
+    /** Served path, mount prefix included. Always starts with "/". */
+    from: string;
+    /** Served path or an absolute external URL. */
+    to: string;
+    /** 301 for renames (the default), or whatever the author asked for. */
+    status: number;
+    /** Where the rule came from, for error messages that can be acted on. */
+    origin: "frontmatter" | "aliases" | "config";
+    /** Page slug that declared it, when it came from a page. */
+    declaredBy?: string;
+}
+/** The `redirects:` config block: shorthand string, or an object with a status. */
+export type RedirectsConfig = Record<string, string | {
+    to: string;
+    status?: number;
+}>;
+export interface CollectRedirectsInput {
+    /** Every page the build will emit, for the dangling-target and live-page checks. */
+    pages: {
+        slug: string;
+        redirect?: string;
+        frontmatter?: Record<string, unknown>;
+        multiSource?: {
+            originalSlug?: string;
+        };
+    }[];
+    /** The `redirects:` config block, if any. */
+    config?: RedirectsConfig;
+    /** URL prefix the site is served under (urlBase + basePath), "" when at the root. */
+    prefix: string;
+    /** A rule the build cannot honour is left out with a warning instead of failing (`--allow-broken-redirects`). */
+    lenient?: boolean;
+}
+export interface CollectRedirectsResult {
+    rules: RedirectRule[];
+    /** Fatal — the caller throws. A wrong redirect is worse than none. */
+    errors: string[];
+    /** Non-fatal, printed. Chains are collapsed rather than refused. */
+    warnings: string[];
+}
+/**
+ * A page slug → the path it is served at. Mirrors the emitter: pages are
+ * directories with a trailing slash, `index` is the prefix root.
+ */
+export declare function slugToServedPath(slug: string, prefix: string): string;
+/**
+ * The site-path prefix a page's source is published under (its namespace,
+ * language and version segments, as `latest` or `en/v3`): its slug without
+ * the path the source gave it. "" for a site without those axes.
+ */
+export declare function pageUnitPrefix(page: {
+    slug: string;
+    multiSource?: {
+        originalSlug?: string;
+    };
+}): string;
+/**
+ * A path written in a page's front matter (`redirect:`, `aliases:`) as a site
+ * path: relative to the page's unit (its language and version), unless it
+ * already starts with it, as dogsbay-ssg reads it (issue #096). A copied
+ * version (`latest` snapshotted to `v4/`) keeps its redirects inside itself.
+ * `mount` (urlBase + basePath) may be written or not; URLs pass through.
+ */
+export declare function inPageUnit(raw: string, unit: string, mount: string): string;
+/**
+ * Normalize an authored path to the served form: leading slash, mount prefix
+ * applied once, trailing slash unless it names a file. External URLs pass
+ * through untouched.
+ */
+export declare function normalizeTarget(raw: string, prefix: string): string;
+/**
+ * Gather every declared redirect, resolve paths, and refuse the ones that
+ * would be wrong at runtime. Pure — `errors` is the caller's cue to throw.
+ */
+export declare function collectRedirects(input: CollectRedirectsInput): CollectRedirectsResult;
+/** The `_redirects` file Workers Static Assets reads from the assets root. */
+export declare function renderRedirectsFile(rules: RedirectRule[]): string;
+/**
+ * A static stub for hosts with no redirect mechanism (GitHub Pages, plain
+ * static hosting). This is a genuine downgrade and is reported as one: the
+ * response is 200, and the redirect is a hint rather than a status code.
+ * `noindex` plus a canonical keeps crawlers pointed at the real page.
+ */
+export declare function renderMetaRefreshPage(rule: RedirectRule, siteUrl?: string): string;
+/**
+ * Where a stub page goes inside `public/`, relative to it. The served path
+ * already carries the mount prefix, but `public/` is copied into the mount
+ * directory, so the prefix is stripped back off here — otherwise the stub
+ * lands at `<mount>/<mount>/old/`.
+ */
+export declare function stubPathForRule(rule: RedirectRule, prefix: string): string;

package/dist/redirects.js

@@ -0,0 +1,223 @@
+/**
+ * Redirects — `redirect:` / `aliases:` frontmatter and the `redirects:` config
+ * key, turned into rules and then into whatever the deploy target can honour.
+ *
+ * See plans/redirects-and-aliases.md. Three things drove the design:
+ *
+ * 1. **`redirect:` was accepted everywhere and emitted nowhere.** The schema
+ *    took it, `ExportPage` carried it, the sitemap excluded the page and
+ *    `format-dogsbay-md` round-tripped it — and `format-astro` wrote a normal
+ *    empty page. Four consumers honouring a field is what made it look
+ *    supported. So the page skip lives here too, not just the rule.
+ *
+ * 2. **A rule's paths are SERVED paths.** Cloudflare matches the request path,
+ *    which carries the mount prefix. `/old → /new` on a site mounted at
+ *    `/blog` must be written `/blog/old → /blog/new` or it never fires.
+ *
+ * 3. **Trailing slashes decide whether a redirect costs one hop or two.**
+ *    Sites serve `/guide/auth/` (docs-dev/url-shape.md). A rule targeting
+ *    `/guide/auth` redirects to a path that itself redirects. Internal paths
+ *    are normalized to the served form.
+ *
+ * This module is pure: it does no IO, so every rule and every refusal is
+ * testable without building a site.
+ */
+import { isExternalUrl, renderRedirectStub, renderRedirectsFile as renderRedirectsLines, resolveRedirects, } from "@dogsbay/site-files";
+const VALID_STATUS = new Set([301, 302, 303, 307, 308]);
+const isExternal = isExternalUrl;
+/**
+ * A page slug → the path it is served at. Mirrors the emitter: pages are
+ * directories with a trailing slash, `index` is the prefix root.
+ */
+export function slugToServedPath(slug, prefix) {
+    const clean = slug.replace(/^\/+|\/+$/g, "").replace(/(^|\/)index$/, "");
+    const base = prefix.replace(/\/+$/, "");
+    if (!clean)
+        return `${base}/`;
+    return `${base}/${clean}/`;
+}
+/**
+ * The site-path prefix a page's source is published under (its namespace,
+ * language and version segments, as `latest` or `en/v3`): its slug without
+ * the path the source gave it. "" for a site without those axes.
+ */
+export function pageUnitPrefix(page) {
+    const clean = (s) => s.replace(/^\/+|\/+$/g, "").replace(/(^|\/)index$/, "");
+    const slug = clean(page.slug);
+    const inside = clean(page.multiSource?.originalSlug ?? page.slug);
+    if (!inside)
+        return slug;
+    if (slug === inside)
+        return "";
+    return slug.endsWith(`/${inside}`) ? slug.slice(0, -inside.length - 1) : "";
+}
+/**
+ * A path written in a page's front matter (`redirect:`, `aliases:`) as a site
+ * path: relative to the page's unit (its language and version), unless it
+ * already starts with it, as dogsbay-ssg reads it (issue #096). A copied
+ * version (`latest` snapshotted to `v4/`) keeps its redirects inside itself.
+ * `mount` (urlBase + basePath) may be written or not; URLs pass through.
+ */
+export function inPageUnit(raw, unit, mount) {
+    if (!unit || isExternal(raw))
+        return raw;
+    const t = raw.trim();
+    const cut = t.search(/[?#]/);
+    const suffix = cut < 0 ? "" : t.slice(cut);
+    let p = (cut < 0 ? t : t.slice(0, cut)).replace(/^\/+/, "");
+    const m = mount.replace(/^\/+|\/+$/g, "");
+    if (m && (p === m || p.startsWith(`${m}/`)))
+        p = p.slice(m.length).replace(/^\/+/, "");
+    if (!(p === unit || p.startsWith(`${unit}/`)))
+        p = p ? `${unit}/${p}` : unit;
+    return `/${p}${suffix}`;
+}
+/**
+ * Normalize an authored path to the served form: leading slash, mount prefix
+ * applied once, trailing slash unless it names a file. External URLs pass
+ * through untouched.
+ */
+export function normalizeTarget(raw, prefix) {
+    if (isExternal(raw))
+        return raw;
+    // A "#anchor" or "?query" stays on the target as written; only the path is
+    // normalized (it used to become "/a#x/", which matched no page).
+    const trimmed = raw.trim();
+    const cut = trimmed.search(/[?#]/);
+    const suffix = cut < 0 ? "" : trimmed.slice(cut);
+    let p = cut < 0 ? trimmed : trimmed.slice(0, cut);
+    if (!p.startsWith("/"))
+        p = `/${p}`;
+    const base = prefix.replace(/\/+$/, "");
+    if (base && p !== base && !p.startsWith(`${base}/`)) {
+        p = `${base}${p}`;
+    }
+    const last = p.split("/").pop() ?? "";
+    if (!last.includes(".") && !p.endsWith("/"))
+        p = `${p}/`;
+    return p + suffix;
+}
+/**
+ * Gather every declared redirect, resolve paths, and refuse the ones that
+ * would be wrong at runtime. Pure — `errors` is the caller's cue to throw.
+ */
+export function collectRedirects(input) {
+    const { pages, config, prefix } = input;
+    const errors = [];
+    const warnings = [];
+    const livePaths = new Set();
+    for (const page of pages) {
+        // A page that only redirects is not a live page — it is the thing being
+        // redirected away from, and emitAstroPages skips it.
+        if (!page.redirect)
+            livePaths.add(slugToServedPath(page.slug, prefix));
+    }
+    // Duplicates are resolved (and reported) by resolveRedirects.
+    const candidates = [];
+    const add = (rule) => {
+        candidates.push(rule);
+    };
+    // 1. Page frontmatter: `redirect:` (this page forwards) and `aliases:` (old
+    //    paths that forward TO this page).
+    for (const page of pages) {
+        const here = slugToServedPath(page.slug, prefix);
+        // Front matter paths are relative to the page's language and version (#096).
+        const unit = pageUnitPrefix(page);
+        if (page.redirect) {
+            add({
+                from: here,
+                to: normalizeTarget(inPageUnit(page.redirect, unit, prefix), prefix),
+                status: 301,
+                origin: "frontmatter",
+                declaredBy: page.slug,
+            });
+        }
+        const aliases = page.frontmatter?.aliases;
+        if (aliases !== undefined) {
+            if (!Array.isArray(aliases) || aliases.some((a) => typeof a !== "string")) {
+                errors.push(`aliases: on ${page.slug} must be a list of paths. ` +
+                    `To fix: use a YAML list of strings.`);
+            }
+            else {
+                for (const alias of aliases) {
+                    add({
+                        from: normalizeTarget(inPageUnit(alias, unit, prefix), prefix),
+                        to: here,
+                        status: 301,
+                        origin: "aliases",
+                        declaredBy: page.slug,
+                    });
+                }
+            }
+        }
+    }
+    // 2. Config, which wins over frontmatter for the same source.
+    for (const [from, value] of Object.entries(config ?? {})) {
+        const to = typeof value === "string" ? value : value.to;
+        const status = typeof value === "string" ? 301 : (value.status ?? 301);
+        if (typeof to !== "string" || !to.trim()) {
+            errors.push(`redirects: entry "${from}" has no target. To fix: give it a path or URL.`);
+            continue;
+        }
+        if (!VALID_STATUS.has(status)) {
+            errors.push(`redirects: entry "${from}" has status ${status}. ` +
+                `To fix: use one of ${[...VALID_STATUS].join(", ")}.`);
+            continue;
+        }
+        add({
+            from: normalizeTarget(from, prefix),
+            to: normalizeTarget(to, prefix),
+            status,
+            origin: "config",
+        });
+    }
+    const resolved = resolveRedirects(candidates, {
+        strict: input.lenient !== true,
+        // A target's "#anchor" or "?query" is not part of the page it names.
+        isPage: (path) => livePaths.has(path.split(/[?#]/)[0]),
+        cloudflareLimits: true,
+    });
+    return {
+        rules: resolved.rules,
+        errors: [...errors, ...resolved.errors],
+        warnings: [...warnings, ...resolved.warnings],
+    };
+}
+/** The `_redirects` file Workers Static Assets reads from the assets root. */
+export function renderRedirectsFile(rules) {
+    return renderRedirectsLines(rules);
+}
+/**
+ * A static stub for hosts with no redirect mechanism (GitHub Pages, plain
+ * static hosting). This is a genuine downgrade and is reported as one: the
+ * response is 200, and the redirect is a hint rather than a status code.
+ * `noindex` plus a canonical keeps crawlers pointed at the real page.
+ */
+export function renderMetaRefreshPage(rule, siteUrl) {
+    const canonical = siteUrl && !isExternal(rule.to)
+        ? `${siteUrl.replace(/\/+$/, "")}${rule.to}`
+        : isExternal(rule.to)
+            ? rule.to
+            : undefined;
+    return renderRedirectStub(rule.to, canonical);
+}
+/**
+ * Where a stub page goes inside `public/`, relative to it. The served path
+ * already carries the mount prefix, but `public/` is copied into the mount
+ * directory, so the prefix is stripped back off here — otherwise the stub
+ * lands at `<mount>/<mount>/old/`.
+ */
+export function stubPathForRule(rule, prefix) {
+    const base = prefix.replace(/\/+$/, "");
+    let p = rule.from;
+    if (base && p.startsWith(base))
+        p = p.slice(base.length);
+    p = p.replace(/^\/+|\/+$/g, "");
+    // The stub is written at this path under public/. resolveRedirects refuses
+    // such a source already; this is the last line before a file write, so a
+    // `..` that reached it some other way cannot leave the site.
+    if (p.split("/").some((seg) => seg === ".." || seg === ".") || /[\\\u0000]/.test(p)) {
+        throw new Error(`redirect source ${JSON.stringify(rule.from)} would write outside the site`);
+    }
+    return p ? `${p}/index.html` : "index.html";
+}

package/dist/serialize.d.ts

@@ -19,12 +19,25 @@ export interface AstroGenOptions {
     imageOptimization?: boolean;
     /** Controls CodeBlock title bar: true = always (default), "auto" = only with explicit title */
     codeBlockTitle?: boolean | "auto";
+    /** A paragraph that is one titled image renders as a captioned figure (`content.imageCaptions: title`). */
+    imageCaptions?: boolean;
+    /**
+     * Combined URL prefix (urlBase + basePath). When non-empty, the
+     * caller is expected to have already pre-rewritten absolute image
+     * srcs in the tree to include this prefix; the serializer uses
+     * the prefix only to strip it back off for the imageMap lookup
+     * key (which is keyed off the unprefixed publicPath built via
+     * `import.meta.glob` at runtime).
+     */
+    combinedPrefix?: string;
 }
+import { TONE_CLASSES } from "./tone-classes.js";
+export { TONE_CLASSES };
 /** Escape for use inside an Astro {expression}. Uses JSON.stringify for safety. */
 export declare function escapeExpr(s: string): string;
 /** Escape for use in an HTML attribute value (double-quoted). */
 export declare function escapeAttr(s: string): string;
+export declare function componentAttr(name: string, value: string): string;
 /** Escape text for use directly in an Astro template (not inside an expression). */
 export declare function escapeTemplate(s: string): string;
 export declare function treeToAstro(nodes: TreeNode[], options?: AstroGenOptions): AstroGenResult;
-//# sourceMappingURL=serialize.d.ts.map