@escape-game-over/atlas 0.1.1

package/src/routes/resolve.ts

@@ -0,0 +1,266 @@
+import type { StringKeys } from "../types.ts";
+import type { UrlPath } from "../url.ts";
+import type { RouteOverride, RouteRegistry, RouteSitemap } from "./define.ts";
+
+export interface ResolvedRoute<L extends string, Id extends string = string> {
+    readonly id: Id;
+    /** Fallback slug, used by every locale without its own translation. */
+    readonly slug: string;
+    readonly slugByLocale: Readonly<Partial<Record<L, string>>>;
+    readonly enabled: boolean;
+    /** How many pages this route's list runs to. `1` is an ordinary route. */
+    readonly pages: number;
+    readonly sitemap: RouteSitemap | undefined;
+}
+
+export type ResolvedRoutes<L extends string, Id extends string> = Readonly<
+    Record<Id, ResolvedRoute<L, Id>>
+>;
+
+/** How many path segments a slug has. `""` is one, the locale root. */
+function segmentCount(slug: string): number {
+    return slug.split("/").length;
+}
+
+/** The slug a route uses in one locale: its translation, else the fallback. */
+export function slugFor<L extends string>(
+    route: ResolvedRoute<L, string>,
+    locale: L
+): string {
+    return route.slugByLocale[locale] ?? route.slug;
+}
+
+/**
+ * How many pages a route's list runs to, settled once for everyone who reads it.
+ *
+ * Resolved here rather than defended at each use, because it was read in two
+ * places that disagreed: the entry builder clamped it to at least one and built
+ * the page, while `pathFor` compared against the raw number and refused to link
+ * it. A route with `pages: 0` therefore produced a file nothing in the project
+ * was allowed to point at. One value, decided at the boundary, and neither
+ * reader has an opinion left to hold.
+ *
+ * **Zero normalises to one**, and is the reason this is not simply a check. It
+ * is what a list divided by a page size returns when there is nothing in it —
+ * `Math.ceil(0 / 12)` — and a news index with no posts is still a page you can
+ * open. Making that a build error would push a `Math.max(1, …)` into every
+ * project that paginates, which is the rule living in four repos instead of
+ * here.
+ *
+ * **Anything else invalid throws**, for the reason `checkEntryLimit` throws:
+ * normalise a wrong value that plainly means something, refuse one that does
+ * not. A negative page count and a fractional one mean nothing — no list
+ * produces them — so they are typos, and a typo quietly clamped to 1 is a route
+ * that silently stops paginating.
+ */
+function pageCount(pages: number | undefined, id: string): number {
+    if (pages === undefined || pages === 0) return 1;
+
+    if (!Number.isInteger(pages) || pages < 0) {
+        throw new Error(
+            `Route "${id}" has pages: ${pages}, which is not a number of pages a list can run to: it wants a whole number from 0, where 0 and 1 both mean the single page an empty list still has.`
+        );
+    }
+    return pages;
+}
+
+/**
+ * Merges a project's route overlay over the base registry.
+ *
+ * Slug translations merge key by key, so a project can retranslate one locale
+ * without restating the others.
+ */
+export function mergeRoutes<L extends string, Base extends RouteRegistry<L>>(
+    base: Base,
+    overrides: Readonly<Partial<Record<StringKeys<Base>, RouteOverride<L>>>>
+): ResolvedRoutes<L, StringKeys<Base>> {
+    type Id = StringKeys<Base>;
+    const merged: Record<string, ResolvedRoute<L, Id>> = {};
+
+    for (const [id, data] of Object.entries<RouteRegistry<L>[string]>(base)) {
+        const override = overrides[id as Id];
+        merged[id] = {
+            id: id as Id,
+            slug: override?.slug ?? data.slug,
+            // Spreading two partials of a generic Record widens to `{}`, so the
+            // shape is restated rather than inferred.
+            slugByLocale: {
+                ...data.slugByLocale,
+                ...override?.slugByLocale,
+            } as Readonly<Partial<Record<L, string>>>,
+            enabled: override?.enabled ?? data.enabled,
+            // A project's count wins outright rather than merging: how much
+            // this deployment has published is not a variation on the shared
+            // table's number, it replaces it. Normalised here so every reader
+            // downstream sees the same count — see `pageCount`.
+            pages: pageCount(override?.pages ?? data.pages, id),
+            sitemap: override?.sitemap ?? data.sitemap,
+        };
+    }
+
+    return merged as ResolvedRoutes<L, Id>;
+}
+
+export interface PathContext<L extends string> {
+    readonly defaultLocale: L;
+    /** When true every locale is prefixed, including the default one. */
+    readonly prefixDefaultLocale: boolean;
+    /**
+     * The segment that marks a page of a list — `"page"`, giving
+     * `/news/page/2`.
+     *
+     * Translated like any other slug, because it appears in a URL beside slugs
+     * that are: `/el-GR/nea/selida/2`. Locales left out fall back to the
+     * default.
+     *
+     * A segment of its own rather than `/news/2`, so that a post slugged with a
+     * number cannot collide with a page number — and so the URL says which of
+     * the two it is.
+     */
+    readonly pageSegment: string;
+    readonly pageSegmentByLocale?: Readonly<Partial<Record<L, string>>>;
+}
+
+/** The word this locale spells the page segment with. */
+export function pageSegmentFor<L extends string>(
+    locale: L,
+    ctx: PathContext<L>
+): string {
+    return ctx.pageSegmentByLocale?.[locale] ?? ctx.pageSegment;
+}
+
+/**
+ * The path of one page of a route's list.
+ *
+ * Page 1 is the bare path, never `.../page/1`: the two would be the same list
+ * at two URLs, which is a duplicate to canonicalise away rather than a page to
+ * publish.
+ */
+export function pagePath<L extends string>(
+    base: UrlPath,
+    page: number,
+    locale: L,
+    ctx: PathContext<L>
+): UrlPath {
+    if (page <= 1) return base;
+
+    const segment = pageSegmentFor(locale, ctx);
+    // The locale root is `/`, and joining onto it would double the slash.
+    return base === "/" ? `/${segment}/${page}` : `${base}/${segment}/${page}`;
+}
+
+export function localePrefix<L extends string>(
+    locale: L,
+    ctx: PathContext<L>
+): "" | UrlPath {
+    return locale === ctx.defaultLocale && !ctx.prefixDefaultLocale
+        ? ""
+        : `/${locale}`;
+}
+
+/**
+ * Joins a locale prefix and a slug into an absolute, trailing-slash-free path.
+ *
+ * Returns `UrlPath`, so the leading slash is a fact the type carries rather
+ * than a convention every caller has to trust: every absolute URL lib emits is
+ * this value concatenated onto an origin.
+ */
+export function buildPath<L extends string>(
+    slug: string,
+    locale: L,
+    ctx: PathContext<L>
+): UrlPath {
+    const trimmed = slug.replace(/^\/+|\/+$/g, "");
+    const prefix = localePrefix(locale, ctx);
+    const path: "" | UrlPath = trimmed === "" ? prefix : `${prefix}/${trimmed}`;
+    return path === "" ? "/" : path;
+}
+
+export interface RouteEntry<L extends string, Id extends string = string> {
+    readonly routeId: Id;
+    readonly locale: L;
+    readonly path: UrlPath;
+    /**
+     * Which page of the route's list this is, from 1.
+     *
+     * Every entry has one, and for the vast majority it is `1` — an ordinary
+     * page is the first and only page of itself. Readers that do not paginate
+     * can ignore it; the ones that must tell page 3 from an article cannot.
+     */
+    readonly page: number;
+    readonly sitemap: RouteSitemap | undefined;
+}
+
+/**
+ * Every (route, locale) pair this build should emit.
+ *
+ * Collisions throw. Since untranslated locales fall back to the default slug,
+ * two routes can collide in one locale while differing in another — this is the
+ * check that turns that into a build failure instead of a page silently
+ * overwriting another.
+ */
+export function listRouteEntries<L extends string, Id extends string>(
+    routes: ResolvedRoutes<L, Id>,
+    locales: readonly L[],
+    ctx: PathContext<L>
+): readonly RouteEntry<L, Id>[] {
+    const entries: RouteEntry<L, Id>[] = [];
+    const seen = new Map<string, string>();
+
+    for (const route of Object.values<ResolvedRoute<L, Id>>(routes)) {
+        // Depth is checked before the `enabled` guard, so a switched-off page is
+        // validated too — the alternative is a broken translation lying dormant
+        // until the day someone turns the page on.
+        //
+        // A backstop rather than the main check: `defineRoutes` and
+        // `defineRouteOverrides` both reject this at compile time. What survives
+        // to here is a slug that was typed as plain `string` — computed, or read
+        // from an env var — where the literal comparison passed vacuously.
+        const depth = segmentCount(route.slug);
+        for (const [locale, translated] of Object.entries<string | undefined>(
+            route.slugByLocale
+        )) {
+            // A locale with no translation falls back to the slug, so it is at
+            // the right depth by construction.
+            if (translated === undefined) continue;
+            if (segmentCount(translated) !== depth) {
+                throw new Error(
+                    `Route "${route.id}" resolves to "${route.slug}" (${depth} segments) but "${translated}" (${segmentCount(translated)}) in locale "${locale}". Every locale of a route must sit at the same depth.`
+                );
+            }
+        }
+
+        if (!route.enabled) continue;
+
+        for (const locale of locales) {
+            const base = buildPath(slugFor(route, locale), locale, ctx);
+
+            // One entry per page of the list, page 1 being the bare path. A
+            // route that does not paginate has `pages: 1` and so runs once,
+            // which is why nothing below is conditional on paginating.
+            //
+            // Read straight, with no clamp of its own: `mergeRoutes` settled
+            // the count, and a second opinion here is what let this build a
+            // page that `pathFor` then refused to link.
+            for (let page = 1; page <= route.pages; page++) {
+                const path = pagePath(base, page, locale, ctx);
+                const owner = seen.get(path);
+                if (owner !== undefined) {
+                    throw new Error(
+                        `Routes "${owner}" and "${route.id}" both resolve to "${path}" in locale "${locale}".`
+                    );
+                }
+                seen.set(path, route.id);
+                entries.push({
+                    routeId: route.id,
+                    locale,
+                    path,
+                    page,
+                    sitemap: route.sitemap,
+                });
+            }
+        }
+    }
+
+    return entries;
+}

package/src/site/api.ts

@@ -0,0 +1,354 @@
+import type { ResolvedLocaleMeta } from "../config.ts";
+import type { GeneratedFile } from "../file.ts";
+import type { PublicFilePath } from "../files.ts";
+import type { TranslateFor } from "../i18n/translate.ts";
+import type { LlmsSection } from "../llms.ts";
+import type { ThemeColor } from "../meta/index.ts";
+import type {
+    RedirectRule,
+    ResolvedRedirect,
+    ValidateRedirectTargets,
+} from "../redirects.ts";
+import type { RobotsGroup } from "../robots.ts";
+import type { RouteEntry } from "../routes/resolve.ts";
+import type { Sitemap } from "../sitemap.ts";
+import type { HttpsUrl, UrlPath } from "../url.ts";
+import type {
+    Alternate,
+    Crumb,
+    LinkOptions,
+    LocaleLink,
+    PageContent,
+    PageMeta,
+    StaticPath,
+} from "./page.ts";
+
+/**
+ * The API a project's pages are written against, and the types read back off it.
+ *
+ * Declared apart from `create.ts`, which builds one. This is the half worth
+ * reading — every method carries why it exists and what it refuses to do — and
+ * it stays legible only while it is not interleaved with the closure that
+ * satisfies it.
+ */
+
+/**
+ * What `llms.txt` needs that lib cannot know: the words.
+ *
+ * Every URL, every grouping and every language line is derived — what is left is
+ * copy, which lives in the consumer's catalog under whatever key convention it
+ * chose. `describe` is how it hands those over without lib having to guess at
+ * message keys.
+ */
+export interface LlmsOptions<
+    RouteId extends string,
+    L extends string,
+    Prefix extends string = string,
+    OrphanPrefix extends string = Prefix,
+> {
+    /**
+     * This route's name and one-line summary, in the file's language.
+     *
+     * A callback rather than a table, so it can read the same catalog the pages
+     * do — the alternative is restating every title next to every route and
+     * letting the two drift.
+     *
+     * Optional, and worth supplying: without it a page is listed under its route
+     * id and no summary, which is a far poorer file — but still a real map of
+     * the site, which is why lib falls back rather than refusing to write one.
+     */
+    describe?(
+        id: RouteId,
+        locale: L
+    ): { readonly name: string; readonly description?: string };
+    /** Heading for pages that are not part of a nested group. Defaults to `"Pages"`. */
+    readonly pagesHeading?: string;
+    /**
+     * Heading for the group of pages nested under one URL segment — `prefix` is
+     * that segment, e.g. `"challenges"`.
+     *
+     * Defaults to the name of the page that owns the bare prefix, so a family
+     * with an index page is titled by it and needs nothing here. Supply this
+     * when there is no such page, or when the group should be called something
+     * other than the page heading it: without it the fallback is the URL
+     * segment itself, which is an identifier rather than a name.
+     *
+     * Return `undefined` for the groups you do not want to name, and each falls
+     * back on its own — naming one group is not a commitment to name them all.
+     *
+     * `prefix` is the union of segments the routes actually produce, not a bare
+     * string, so a near miss like `"challenge"` is a compile error rather than a
+     * comparison that quietly never matches and leaves the default in place.
+     */
+    sectionHeading?(prefix: Prefix, locale: L): string | undefined;
+    /**
+     * Where a section with no index page should link.
+     *
+     * Separate from the heading because it is an enrichment rather than half of
+     * one decision: a section can be renamed without being linked, and linked
+     * without being renamed.
+     *
+     * Only sections that *have* no page of their own are offered. Where an index
+     * page exists it is already the link, and `OrphanPrefix` excludes it — so
+     * pointing a named family somewhere other than the page it is named after is
+     * a compile error rather than a choice. Returning `undefined` leaves the
+     * heading unlinked, which is the right answer when those pages are listed
+     * nowhere else.
+     */
+    sectionLink?(prefix: OrphanPrefix, locale: L): RouteId | undefined;
+    /** The `>` block under the title: what this site is, in a sentence or two. */
+    readonly summary?: string;
+    /**
+     * Sections appended after the derived ones — an address, opening hours, a
+     * phone number. Everything lib has no way to know.
+     */
+    readonly sections?: readonly LlmsSection[];
+    /** Which language to write the file in. Defaults to the site's default. */
+    readonly locale?: L;
+}
+
+/**
+ * Everything the pages need, derived from the data handed in.
+ *
+ * `RouteId` is narrowed to the routes this project actually builds, so linking
+ * to a switched-off page does not type-check.
+ */
+export interface Site<
+    L extends string,
+    Catalog,
+    RouteId extends string,
+    /**
+     * The URL segments that head a group of nested pages, for `llms()`.
+     *
+     * Defaulted, so the three-argument form still names a valid type — this
+     * says nothing about what the site *is*, only what its section names may
+     * be, and no annotation should have to state it.
+     */
+    Prefix extends string = string,
+    /** Of those, the ones with no index page of their own. */
+    OrphanPrefix extends string = Prefix,
+> {
+    readonly locales: readonly L[];
+    readonly defaultLocale: L;
+    readonly prefixDefaultLocale: boolean;
+    /**
+     * This deployment's origin, guaranteed `https://` and without a trailing
+     * slash — `createSite` throws on anything else before this is handed back.
+     *
+     * Typed rather than left as `string` so everything built from it inherits
+     * the guarantee: every absolute URL below is a template on this value, so
+     * they are all `https://…` without a check of their own, and a structured
+     * -data node can demand one.
+     */
+    readonly url: HttpsUrl;
+    /** The publisher's name, as declared by the project. */
+    readonly siteName: string;
+    /**
+     * The project's brand colour, as declared for the browser UI.
+     *
+     * Exposed so anything drawing in the site's colours — a share image, an
+     * embedded SVG — reads the brand from one place rather than restating a hex
+     * value that then drifts from the one every page's `<head>` carries.
+     */
+    readonly themeColor: ThemeColor;
+    readonly localeMeta: Readonly<Record<L, ResolvedLocaleMeta>>;
+    /**
+     * Every route this project builds, in the order the base registry declares
+     * them. Derived — a project never lists these. Build menus by filtering it.
+     */
+    readonly routes: readonly RouteId[];
+
+    /** A locale-bound `t()`. */
+    translate(locale: L): TranslateFor<Catalog>;
+
+    /** Absolute path of a route in one locale, e.g. `/el/sxetika-me-emas`. */
+    pathFor(id: RouteId, locale: L, options?: LinkOptions): UrlPath;
+    /** The same, prefixed with the site origin — for canonicals and sitemaps. */
+    urlFor(id: RouteId, locale: L, options?: LinkOptions): HttpsUrl;
+    /**
+     * Absolute URL of a file served verbatim from `public/`.
+     *
+     * The path half needs no helper — a file in `public/` is served at the path
+     * it sits at, so the literal *is* the link. What is not free is the origin,
+     * which only the project knows, and which anything leaving the page needs:
+     * a share link, a redirect target, structured data.
+     *
+     * Unchecked by lib, which cannot see the directory. Narrow the argument with
+     * the `PublicFile` union that `publicFiles()` generates.
+     */
+    fileUrl(path: PublicFilePath): HttpsUrl;
+
+    /** One entry per published locale, for `hreflang` tags. */
+    alternatesFor(id: RouteId, options?: LinkOptions): readonly Alternate<L>[];
+
+    /**
+     * The same, ready to render as a language switcher: each locale's own label
+     * and writing direction, and which one the reader is on.
+     *
+     * Switching language keeps the page — `about` stays `about`, so `/about-us`
+     * leads to `/el-GR/sxetika-me-emas` rather than dumping the reader home.
+     */
+    localeLinksFor(
+        id: RouteId,
+        current: L,
+        options?: LinkOptions
+    ): readonly LocaleLink<L>[];
+
+    /**
+     * The trail from the site root to one page: root, each ancestor this project
+     * builds, then the page itself.
+     *
+     * Derived from the slug rather than declared, so it cannot disagree with the
+     * URLs — a retranslated slug moves the trail with it, and a page nobody
+     * nests under simply has none. `name` supplies the words, which lib does not
+     * have; it is called for every step including the root.
+     *
+     * An ancestor this project does not build is left out rather than linked: a
+     * crumb pointing at a page that was never generated is a link to a 404, and
+     * structured data will not accept an intermediate step without a URL. That
+     * gap is warned about, once per segment.
+     *
+     * A trail of one is a page with no ancestors — that is not a trail, and
+     * marking it up as one gets nothing rendered.
+     */
+    breadcrumbFor(
+        id: RouteId,
+        locale: L,
+        name: (id: RouteId) => string
+    ): readonly Crumb[];
+
+    /**
+     * URL segments this project builds pages *under* but not *at*.
+     *
+     * A structural fact, so it is stated once rather than discovered by whatever
+     * page renders first: every breadcrumb passing through one of these has a
+     * gap in it. `siteRoutes` reports them at build and at dev-server start.
+     */
+    readonly orphanSegments: readonly string[];
+
+    /** Every (route, locale) pair this build emits. Throws on colliding URLs. */
+    readonly entries: readonly RouteEntry<L, RouteId>[];
+
+    /**
+     * Every page to generate, as `{ params, props }` for a catch-all route.
+     *
+     * `param` is the name of the rest parameter in the router's filename, e.g.
+     * `"route"` for `[...route].astro`. The root path is emitted as `undefined`,
+     * which is what such routers expect.
+     *
+     * When every locale is prefixed nothing owns `/`, and no page is generated
+     * for it: `redirects()` claims it with a 301 to the default locale's root
+     * instead, which is a real redirect rather than a rendered stub. The target
+     * is whichever route has an empty slug — lib has no notion of a "home"
+     * page, so the caller does not have to name one.
+     *
+     * Returns a fresh mutable array, because SSG routers typically demand one.
+     */
+    staticPaths(param: string): StaticPath<L, RouteId>[];
+
+    /**
+     * The rendered sitemap: `entry` is the file to submit, `files` is everything
+     * that must be served (an index plus parts once it splits).
+     */
+    sitemap(): Sitemap;
+
+    /**
+     * The rendered `robots.txt`, already pointing at this site's sitemap.
+     *
+     * Site-wide crawl rules live here rather than in a `robots` meta tag, which
+     * only speaks for its own page and has to be fetched to be read.
+     */
+    robots(groups?: readonly RobotsGroup[]): GeneratedFile;
+
+    /**
+     * Where this site's `llms.txt` is published, or `undefined` if the config
+     * turned it off.
+     *
+     * Public because it is a promise made in two places at once: every page's
+     * head links to this URL, and something has to write a file there. It is
+     * what `siteRoutes` checks so the two cannot disagree.
+     */
+    readonly llmsUrl: HttpsUrl | undefined;
+
+    /**
+     * The rendered `llms.txt`: a map of the site for readers that want the
+     * content rather than the markup.
+     *
+     * lib derives the structure — which pages exist, their URLs, how they nest,
+     * the sitemap and language lines — and asks you only for the words, through
+     * `describe`. That split is the point: a hand-written file of links is stale
+     * the first time a route is switched off or a slug is retranslated, and
+     * nothing reports it, because nothing reads the file during a build.
+     */
+    llms(
+        options?: LlmsOptions<RouteId, L, Prefix, OrphanPrefix>
+    ): GeneratedFile;
+
+    /**
+     * Old URLs that must keep working, resolved and rendered.
+     *
+     * A rule's target names a *route*, not a path, so the URL is derived the way
+     * every other link is: a redirect cannot outlive the page it points at, and
+     * a retranslated slug moves it too. External targets are `https://` URLs and
+     * pass through untouched.
+     *
+     * Returns the rules as data. Rendering is a separate step —
+     * `buildCloudflareRedirects` writes the `_redirects` that Cloudflare and
+     * Netlify read, and a host with its own syntax takes these and writes its own.
+     */
+    redirects<const Rules extends readonly RedirectRule<RouteId, L>[]>(
+        rules: Rules & ValidateRedirectTargets<Rules>
+    ): readonly ResolvedRedirect[];
+
+    /**
+     * Everything the document head needs for one page: the `<html>` attributes,
+     * plus title, description, canonical, `hreflang` alternates, `x-default`,
+     * Open Graph and Twitter — all derived from one place so they cannot
+     * disagree.
+     *
+     * You supply the words and the page's share image; lib supplies the URLs.
+     */
+    metaFor(id: RouteId, locale: L, content: PageContent): PageMeta;
+
+    /**
+     * The head of the 404 page: `<html>` attributes, the title you pass, and
+     * `noindex`.
+     *
+     * No canonical and no share tags — a 404 represents no URL, so there is
+     * nothing for either to name.
+     */
+    notFoundMetaFor(locale: L, title: string): PageMeta;
+}
+
+/** The routes a given site builds, read back off the site's own type. */
+export type RouteIdOf<S> =
+    S extends Site<infer _L, infer _Catalog, infer Id> ? Id : never;
+
+/**
+ * `T` when this site builds route `Id`, `never` when it does not.
+ *
+ * For a value that only makes sense alongside an optional page — a field that
+ * should vanish rather than sit there unread once the page is switched off.
+ */
+export type WhenEnabled<S, Id extends string, T> =
+    Id extends RouteIdOf<S> ? T : never;
+
+/**
+ * A `T` for every route this site builds — and only those.
+ *
+ * Both halves are enforced, which is the point: a page that is built but has no
+ * entry is a missing-property error, and an entry for a page that is *not*
+ * built is an excess-property error. Config can be neither absent nor stale.
+ *
+ * ```ts
+ * const pageConfig = {
+ *     home: { … },
+ *     careers: { … },   // ✗ unless this project enabled `careers`
+ * } satisfies PerRoute<typeof site, PageConfig>;
+ * ```
+ *
+ * Use it with `satisfies`, not an annotation: excess-property checking is what
+ * catches the stale half, and only a literal checked against a known target
+ * gets it.
+ */
+export type PerRoute<S, T> = { readonly [K in RouteIdOf<S>]: T };