@escape-game-over/atlas 0.1.1

package/src/astro/site-routes.ts

@@ -0,0 +1,307 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { AstroIntegration } from "astro";
+import type { GeneratedFile } from "../file.ts";
+import {
+    buildCloudflareRedirects,
+    type ResolvedRedirect,
+} from "../redirects.ts";
+import type { Sitemap } from "../sitemap.ts";
+import type { HttpsUrl } from "../url.ts";
+import { warn } from "../warn.ts";
+
+/**
+ * What this integration needs of a site, and no more.
+ *
+ * Structural rather than `Site<L, Catalog, RouteId>`, so any site satisfies it
+ * without having to name its three type arguments here — and so this states
+ * exactly which parts are used.
+ */
+export interface SiteFiles {
+    readonly url: HttpsUrl;
+    /** Segments with pages under them but none at them; see `orphanSegments`. */
+    readonly orphanSegments: readonly string[];
+    /** Undefined when the site config turned `llms.txt` off. */
+    readonly llmsUrl: HttpsUrl | undefined;
+    sitemap(): Sitemap;
+    robots(): GeneratedFile;
+    llms(): GeneratedFile;
+}
+
+/**
+ * What `updateConfig` accepts: a deep partial of the resolved Astro config.
+ *
+ * Read off the hook rather than named directly. Astro types the parameter as
+ * `DeepPartial<AstroConfig>`, but `DeepPartial` is internal — importing it
+ * means reaching past the package entry point into a path that can move
+ * between releases. `AstroConfig` itself is the wrong type here: it is the
+ * *resolved* config, so annotating a three-key patch with it fails on every
+ * field the patch does not set.
+ */
+type ConfigUpdate = Parameters<
+    Parameters<
+        NonNullable<AstroIntegration["hooks"]["astro:config:setup"]>
+    >[0]["updateConfig"]
+>[0];
+
+/** Byte count of a UTF-8 string, for a log line that says what it cost. */
+function size(body: string): string {
+    const bytes = new TextEncoder().encode(body).length;
+    return bytes < 1024 ? `${bytes} B` : `${(bytes / 1024).toFixed(1)} kB`;
+}
+
+export interface SiteRoutesOptions {
+    /**
+     * The site, imported. Not a module path: everything below is derived from
+     * plain data — URLs, route ids, locales — so it can be built where an Astro
+     * config is evaluated, and a real import is checked where a specifier would
+     * not be.
+     */
+    readonly site: SiteFiles;
+    /** From `site.redirects([…])`. Omit to write no `_redirects`. */
+    readonly redirects?: readonly ResolvedRedirect[];
+    /**
+     * From `site.llms({…})`.
+     *
+     * The finished file rather than a flag, because this is the one output whose
+     * words lib does not have: page names and summaries live in a catalog under
+     * a key convention it cannot guess. Omitting it does not turn the file off —
+     * `site.llms()` still writes one, listing every page by route id with no
+     * summaries. That is a worse file and a real one; switching it off is a
+     * decision, made with `llms: false` in the site config.
+     */
+    readonly llms?: GeneratedFile;
+    /** Write the sitemap. Defaults to true. */
+    readonly sitemap?: boolean;
+    /** Write `robots.txt`. Defaults to true. */
+    readonly robots?: boolean;
+}
+
+/**
+ * Emits the files a static site owes the outside world.
+ *
+ * Written into the output directory when the build is done, rather than served
+ * by injected routes. Two reasons, and the first is not a preference:
+ *
+ * - `_redirects` cannot be a page at all. Astro refuses to route anything in
+ *   `src/pages` whose name begins with `_`, and URL-escaping does not help —
+ *   `%5F` is decoded before the entrypoint is opened.
+ * - A route is injected by *entrypoint*, and that file is compiled into the
+ *   build's own module graph, where it cannot see a caller's `site`. Reaching it
+ *   means naming a module in a string and resolving it through a virtual module
+ *   — a lot of machinery, and nothing type-checks the string. None of these
+ *   files needs the asset pipeline or a page context, so none of that buys
+ *   anything.
+ */
+export function siteRoutes(options: SiteRoutesOptions): AstroIntegration {
+    const { site, redirects, llms, sitemap = true, robots = true } = options;
+
+    /** `llms.txt (4.2 kB)` — the name and what it actually weighs. */
+    const describe = (file: GeneratedFile): string =>
+        `${file.name} (${size(file.body)})`;
+
+    // Rebuilt per request in dev and once at the end of a build, rather than
+    // computed here: in dev the site's data changes under the server, and a list
+    // captured when the integration was constructed would serve yesterday's
+    // sitemap until you restarted.
+    const generate = (): GeneratedFile[] => {
+        const files: GeneratedFile[] = [];
+        if (sitemap) files.push(...site.sitemap().files);
+        if (robots) files.push(site.robots());
+        // `llmsUrl` is what every page's head links to, so a file must exist at
+        // it: the described one when given, a bare listing otherwise. Undefined
+        // means the config turned both off.
+        if (site.llmsUrl !== undefined) files.push(llms ?? site.llms());
+        // Length rather than presence: a site with no rules gets no file, not an
+        // empty one.
+        if (redirects?.length) {
+            files.push(
+                buildCloudflareRedirects(redirects, { siteUrl: site.url })
+            );
+        }
+        return files;
+    };
+
+    /**
+     * Said once, at startup, listing every gap together.
+     *
+     * Not raised by `breadcrumbFor`: a page would then report a fact about the
+     * route table, and only the first page to render one would say anything —
+     * which in dev means once per server lifetime, long after you scrolled past.
+     */
+    const reportOrphans = () => {
+        if (site.orphanSegments.length === 0) return;
+
+        warn(
+            "routes",
+            `${site.orphanSegments.length} URL segment${site.orphanSegments.length === 1 ? " has" : "s have"} pages under ${site.orphanSegments.length === 1 ? "it" : "them"} but none at ${site.orphanSegments.length === 1 ? "it" : "them"}: ${site.orphanSegments.map((segment) => `/${segment}`).join(", ")}. Breadcrumbs through ${site.orphanSegments.length === 1 ? "it" : "them"} will have a gap, since structured data will not accept a step without a URL.`
+        );
+    };
+
+    return {
+        name: "site-routes",
+        hooks: {
+            /**
+             * The three settings lib's own output would contradict, set here
+             * rather than asked for.
+             *
+             * Not a preference imposed on a consumer — each is the half of a
+             * contract whose other half this library already wrote:
+             *
+             * - `output: "static"`. Every file below is generated once, at
+             *   build time, from data known then. There is no request to
+             *   render against, and `robots.txt`, the sitemap and `_redirects`
+             *   are written into the output directory by `astro:build:done`,
+             *   which an on-demand build never reaches.
+             * - `build.format: "file"`. lib emits every canonical, `hreflang`,
+             *   sitemap and `llms.txt` URL without a trailing slash. A host
+             *   canonicalising HTML sends `/about-us` to `/about-us/` when the
+             *   file on disk is `about-us/index.html`, and the other way round
+             *   when it is `about-us.html` — so `directory` would leave every
+             *   URL this library publishes redirecting to a different one, with
+             *   nothing in the build to say so.
+             * - `trailingSlash: "ignore"`. Dev-server matching only, and set to
+             *   the one value that cannot contradict the links lib hands out:
+             *   `"always"` would 404 every one of them, and `"never"` would
+             *   refuse a form the host answers with a redirect rather than a
+             *   404 — dev stricter than production, which teaches you nothing.
+             *
+             * Set instead of validated because there is no way to tell a
+             * deliberate `"directory"` from Astro's default: both arrive here
+             * as the same resolved value, so a check could only warn at
+             * everyone or at no one.
+             */
+            "astro:config:setup": ({ updateConfig, logger }) => {
+                // Annotated, not just passed: `updateConfig(config)` alone
+                // would not catch a misspelled key, because excess-property
+                // checking fires on a fresh object literal at the call site and
+                // not on a variable — and every field of the target is
+                // optional, so `buld: {…}` would be assignable and silently do
+                // nothing. The annotation is what makes a typo an error.
+                const config: ConfigUpdate = {
+                    output: "static",
+                    build: { format: "file" },
+                    trailingSlash: "ignore",
+                };
+                updateConfig(config);
+                // Said out loud: a setting changed from under you is worth a
+                // line, and reading `astro.config.ts` would otherwise leave you
+                // to wonder why the output is not shaped the way its defaults
+                // say. One line at startup, naming every value it set.
+                logger.info(
+                    `updated config: ${JSON.stringify(config, null, 2)}`
+                );
+                reportOrphans();
+            },
+
+            /**
+             * The same files, served from memory while developing.
+             *
+             * Without this they exist only after `astro build`: `astro:build:done`
+             * does not run under `astro dev`, so every one of them 404s in the
+             * one place you would go to look at it. They were routes once, which
+             * gave this for free; serving them here is the cost of having moved
+             * them out of the page graph.
+             */
+            "astro:server:setup": ({ server, logger }) => {
+                /**
+                 * The paths this integration answers on, learned by generating
+                 * once and refreshed whenever we generate again.
+                 *
+                 * Its whole job is to keep `generate()` off the hot path. The
+                 * middleware sees every request the dev server takes — each
+                 * page, each asset, each Vite ping — and regenerating for all
+                 * of them rebuilds the sitemap three times over (once directly,
+                 * once inside `robots()`, once inside `llms()`) to answer a
+                 * request for `/favicon.ico`.
+                 *
+                 * A name that appears only later is the one thing this can
+                 * miss: a sitemap crossing `entryLimit` mid-session gains
+                 * `sitemap-0.xml` and friends, which are not in the set until
+                 * something regenerates. Acceptable because the set is
+                 * refreshed on every hit and the dev server restarts on a
+                 * config change — and because the alternative is paying for a
+                 * full generate on every asset request to catch it.
+                 */
+                const served = new Set<string>();
+                const remember = (files: readonly GeneratedFile[]) => {
+                    served.clear();
+                    for (const file of files) served.add(`/${file.name}`);
+                    return files;
+                };
+
+                remember(generate()).map((file) =>
+                    logger.info(`generated ${describe(file)}`)
+                );
+                server.middlewares.use((request, response, next) => {
+                    const path = (request.url ?? "").split("?")[0] ?? "";
+
+                    // The dev server knows nothing about `_redirects`, which is
+                    // a static-host feature applied to the built output. Left
+                    // alone, every redirect 404s in dev — including `/` when
+                    // every locale is prefixed, which is the first URL anyone
+                    // opens. Serving them here makes dev answer as production
+                    // will, rather than as a place where the rules do not exist.
+                    // Matched with and without a trailing slash, because a host
+                    // either normalises one away before its rules run or treats
+                    // the two as the same URL. Dev should not be the only place
+                    // where `/rooms/` misses a rule that `/rooms` hits.
+                    const canonical =
+                        path.length > 1 && path.endsWith("/")
+                            ? path.slice(0, -1)
+                            : path;
+                    const rule = redirects?.find((it) => it.from === canonical);
+                    if (rule !== undefined) {
+                        logger.info(
+                            `redirect: ${path} → ${rule.to} (${rule.status})`
+                        );
+                        response.statusCode = rule.status;
+                        response.setHeader("Location", rule.to);
+                        response.end();
+                        return;
+                    }
+
+                    // Nothing of ours sits at this path, so hand it on without
+                    // building anything. This is the check that keeps the cost
+                    // below off every page and asset request in dev.
+                    if (!served.has(path)) {
+                        next();
+                        return;
+                    }
+
+                    // Regenerated per request, so an edit to a route or a
+                    // message shows up on reload rather than at restart.
+                    const file = remember(generate()).find(
+                        (candidate) => `/${candidate.name}` === path
+                    );
+                    if (file === undefined) {
+                        // The set said this was ours and the fresh build
+                        // disagrees — a file that stopped being generated, so
+                        // it is now a 404 like any other missing path.
+                        next();
+                        return;
+                    }
+                    logger.info(`${path} → ${describe(file)}`);
+                    response.setHeader("Content-Type", file.contentType);
+                    response.end(file.body);
+                });
+            },
+
+            "astro:build:done": async ({ dir, logger }) => {
+                const files = generate();
+
+                await Promise.all(
+                    files.map(async (file) => {
+                        // `name` may carry a subdirectory, and the sitemap's
+                        // does once it splits into numbered parts.
+                        const path = fileURLToPath(new URL(file.name, dir));
+                        await mkdir(dirname(path), { recursive: true });
+                        await writeFile(path, file.body, "utf8");
+                    })
+                );
+                files.map((file) => logger.info(`wrote ${describe(file)}`));
+            },
+        },
+    };
+}

package/src/config.ts

@@ -0,0 +1,218 @@
+import type { LlmsConfig } from "./llms.ts";
+import type { RobotsConfig } from "./robots.ts";
+import type { SitemapConfig } from "./sitemap.ts";
+import type { StringKeys } from "./types.ts";
+
+export interface LocaleMeta {
+    /** Name of the language, written in that language. */
+    readonly label: string;
+    // No language tag here: the locale's own key is the tag. One identifier,
+    // used for the URL segment, `lang`, `hreflang` and `og:locale` alike.
+    readonly dir: "ltr" | "rtl";
+}
+
+/** `LocaleMeta` after defaults are filled in. */
+export interface ResolvedLocaleMeta {
+    readonly label: string;
+    readonly htmlLang: string;
+    readonly dir: "ltr" | "rtl";
+    /** Derived: `htmlLang` with `-` swapped for `_`, which is the OG form. */
+    readonly ogLocale: string;
+}
+
+/**
+ * A well-formed language tag, or `never`.
+ *
+ * The region is required: `en` is rejected, `en-US` accepted. A bare language
+ * leaves the territory to the reader, and `en-US` and `en-GB` differ in spelling,
+ * currency and date order — decisions worth stating rather than inferring.
+ *
+ * Checks shape and casing only, so `en_US`, `en-us` and `EN-US` are all
+ * rejected. It deliberately does not check that the subtags are *real*: the
+ * authoritative list is the IANA Language Subtag Registry, thousands of entries
+ * that would go stale the moment they were copied into this folder.
+ */
+export type LanguageTag<T extends string> =
+    T extends `${infer Lang}-${infer Region}`
+        ? Lang extends Lowercase<Lang>
+            ? Region extends Uppercase<Region>
+                ? T
+                : never
+            : never
+        : never;
+
+interface MalformedLanguageTag<T extends string> {
+    readonly __MALFORMED_LANGUAGE_TAG__: `"${T}" is not a well-formed language tag: expected a lowercase language and an uppercase region, like "en-US"`;
+}
+
+/**
+ * Every locale key must itself be a well-formed tag, since it *is* the tag.
+ *
+ * A malformed key demands a value no object can satisfy, so the error lands on
+ * that locale and names the expected shape.
+ */
+type ValidateLocales<T> = {
+    [K in StringKeys<T>]: [LanguageTag<K>] extends [never]
+        ? MalformedLanguageTag<K>
+        : LocaleMeta;
+};
+
+export interface RoutingConfig<L extends string> {
+    readonly defaultLocale: L;
+    /**
+     * `false` -> default locale at `/`, others at `/<locale>`.
+     * `true`  -> every locale prefixed, and `/` redirects to `/<defaultLocale>`.
+     */
+    readonly prefixDefaultLocale: boolean;
+    /**
+     * The segment marking a page of a paginated list: `/news/page/2`.
+     *
+     * Defaults to `"page"`, which is what Hugo and WordPress produce and what a
+     * reader expects. A segment of its own rather than `/news/2`, so a post
+     * slugged with a number cannot collide with a page number.
+     */
+    readonly pageSegment?: string;
+    /**
+     * Per-locale spellings of it — `{ "el-GR": "selida" }`.
+     *
+     * Translated because it sits in a URL beside slugs that are: leaving an
+     * English word in the middle of `/el-GR/nea/…` is the one untranslated
+     * thing on the page.
+     */
+    readonly pageSegmentByLocale?: Readonly<Partial<Record<L, string>>>;
+}
+
+/**
+ * The shape of `site.config.ts`: which languages exist and how URLs are shaped.
+ *
+ * The per-feature sections are defined by the features themselves, so a change
+ * to what a sitemap can be told reaches this file without editing it.
+ */
+export interface SiteConfigShape {
+    readonly locales: Readonly<Record<string, LocaleMeta>>;
+    /**
+     * The URL shape a project gets unless it says otherwise.
+     *
+     * Named for what it is: a project's `overrideRouting` wins over it, so
+     * reading this file is not enough to know how one deployment's URLs look.
+     */
+    readonly defaultRouting: RoutingConfig<string>;
+    readonly sitemap?: SitemapConfig;
+    readonly robots?: RobotsConfig;
+    /**
+     * `false` to publish no `llms.txt`. Omitted, one is published under the
+     * default name.
+     *
+     * Opt-out like the two above, even though lib cannot write this one
+     * unaided — it needs a name and a summary per page, which only the consumer
+     * has. Forgetting to supply them is a build error rather than a reason to
+     * make the file opt-in: this key is also what puts `<link rel="describedby">`
+     * in every head, and a page cannot tell whether `site.llms()` was called
+     * somewhere, so the declaration stands in for it and `siteRoutes` checks
+     * that it was kept.
+     */
+    readonly llms?: LlmsConfig | false;
+    // No share image here on purpose: an image belongs to the page it
+    // represents, so the page passes its own to `metaFor`.
+}
+
+/** The locale union a site config declares, e.g. `"en" | "el"`. */
+export type LocalesOf<C> = C extends { readonly locales: infer M }
+    ? StringKeys<M>
+    : never;
+
+/**
+ * Declares the site's locale universe and URL shape.
+ *
+ * Every other helper takes this object as its first argument, which is how they
+ * learn the locale union without you ever writing a type argument.
+ *
+ * Enforced at compile time: `defaultRouting.defaultLocale` must be one of
+ * `locales`, and every locale key must be a well-formed language tag.
+ *
+ * Both checks live in the constraint rather than the parameter. In parameter
+ * position a single unrelated mistake widens `T`, every key then resolves to
+ * `string`, and the config reports a cascade of malformed-tag errors on lines
+ * that were fine.
+ */
+export function defineSiteConfig<
+    const T extends SiteConfigShape & {
+        readonly defaultRouting: {
+            readonly defaultLocale: StringKeys<T["locales"]>;
+            // Mapped over the keys actually written, not declared as a
+            // `Partial<Record<…>>`: a constraint is checked by assignability,
+            // and an extra key is assignable to a type whose properties are all
+            // optional. Demanding an impossible value for a bad key is what
+            // makes the error land on that line.
+            readonly pageSegmentByLocale?: {
+                readonly [K in StringKeys<
+                    T["defaultRouting"]["pageSegmentByLocale"]
+                >]: K extends StringKeys<T["locales"]>
+                    ? string
+                    : LocaleNotDeclared<K>;
+            };
+        };
+        readonly locales: ValidateLocales<T["locales"]>;
+    },
+>(config: T): T {
+    return config;
+}
+
+/**
+ * What a project may restate about a locale.
+ *
+ * `dir` is deliberately not here: writing direction is a fact about the script a
+ * language is written in, not a choice a deployment makes. Greek is
+ * left-to-right for everybody, and a project that could say otherwise would only
+ * ever be wrong. The label is the one part that is a matter of taste.
+ */
+export type LocaleMetaOverride = Pick<LocaleMeta, "label">;
+
+/**
+ * Editor-facing error for a locale this site does not declare at all.
+ *
+ * The sibling of `LocaleNotEnabled`, one level up: that one is for a locale the
+ * site has but a project does not publish, this one is for a tag that exists
+ * nowhere — a typo, or a language someone meant to add and did not.
+ */
+export interface LocaleNotDeclared<L extends string> {
+    readonly __LOCALE_NOT_DECLARED__: `locale "${L}" is not among this site's locales, so anything keyed by it would never be read`;
+}
+
+/**
+ * Editor-facing error for anything written for a locale a project does not ship.
+ *
+ * Lives here rather than beside one of its users because two of them need it:
+ * `defineProject`, for locale metadata, and `defineMessageOverrides`, for copy.
+ */
+export interface LocaleNotEnabled<L extends string> {
+    readonly __LOCALE_NOT_ENABLED__: `locale "${L}" is not among this project's enabledLocales, so anything written for it would never be built`;
+}
+
+/**
+ * Applies a project's overrides and derives the tag fields from the key.
+ *
+ * The locale key is the language tag, and `ogLocale` is that tag with `-`
+ * swapped for `_` — Open Graph writes `en_US` where BCP 47 writes `en-US`.
+ */
+export function mergeLocaleMeta<L extends string>(
+    base: Readonly<Record<L, LocaleMeta>>,
+    overrides: Readonly<Partial<Record<L, LocaleMetaOverride>>> | undefined,
+    locales: readonly L[]
+): Readonly<Record<L, ResolvedLocaleMeta>> {
+    const merged: Record<string, ResolvedLocaleMeta> = {};
+    for (const locale of locales) {
+        const defaults = base[locale];
+        if (defaults === undefined) {
+            throw new Error(`No locale metadata for "${locale}".`);
+        }
+        const meta = { ...defaults, ...overrides?.[locale] };
+        merged[locale] = {
+            label: meta.label,
+            dir: meta.dir,
+            htmlLang: locale,
+            ogLocale: locale.replace(/-/g, "_"),
+        };
+    }
+    return merged as Readonly<Record<L, ResolvedLocaleMeta>>;
+}