@escape-game-over/atlas 0.1.1 → 0.1.2

package/src/routes/resolve.ts

@@ -129,6 +129,16 @@ export function pageSegmentFor<L extends string>(
     return ctx.pageSegmentByLocale?.[locale] ?? ctx.pageSegment;
 }
 
+/** A list's base path with a page number hung under the page segment. */
+function underPageSegment(
+    base: UrlPath,
+    segment: string,
+    page: number
+): UrlPath {
+    // The locale root is `/`, and joining onto it would double the slash.
+    return base === "/" ? `/${segment}/${page}` : `${base}/${segment}/${page}`;
+}
+
 /**
  * The path of one page of a route's list.
  *
@@ -144,9 +154,24 @@ export function pagePath<L extends string>(
 ): 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}`;
+    return underPageSegment(base, pageSegmentFor(locale, ctx), page);
+}
+
+/**
+ * The `.../page/1` a list is deliberately *not* published at.
+ *
+ * The counterpart of the rule above: giving page one the bare path leaves the
+ * numbered form unclaimed, and unclaimed is not unasked-for — a reader edits
+ * `/news/page/2` down to `1`, or a crawler assumes a sequence starts where its
+ * segment says. So this is the one path here that exists to be redirected away
+ * from rather than linked, and nothing but `redirects()` should name it.
+ */
+export function pageOneAlias<L extends string>(
+    base: UrlPath,
+    locale: L,
+    ctx: PathContext<L>
+): UrlPath {
+    return underPageSegment(base, pageSegmentFor(locale, ctx), 1);
 }
 
 export function localePrefix<L extends string>(

package/src/site/api.ts

@@ -292,6 +292,18 @@ export interface Site<
      * a retranslated slug moves it too. External targets are `https://` URLs and
      * pass through untouched.
      *
+     * **What comes back is more than what went in.** lib adds the rules the
+     * route table implies, for the URLs its own design leaves unpublished but
+     * reachable: whichever site root the routing mode does not serve — `/` when
+     * every locale is prefixed, `/en-US` when the default locale is not — and
+     * `/news/page/1` for a list whose page one is the bare path. A rule you
+     * state for one of those paths replaces the inferred one, so pass `[]` and
+     * you still get a file worth writing.
+     *
+     * Pages under an unused locale prefix are *not* claimed: that is a rule per
+     * page per language, and it still misses the reader who edits a translated
+     * slug's prefix. See `NOT-BUILT.md`.
+     *
      * 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.

package/src/site/create.ts

@@ -34,6 +34,7 @@ import {
     listRouteEntries,
     mergeRoutes,
     type PathContext,
+    pageOneAlias,
     pagePath,
     type RouteEntry,
     slugFor,
@@ -218,8 +219,31 @@ export function createSite<
         });
     }
 
+    /**
+     * The sitemap, built once and handed to everyone who asks.
+     *
+     * Three callers, and two of them want one string out of it: `robots()` and
+     * `llms()` each advertise `entry.url`, so an unmemoised call derived every
+     * URL on the site — each with its alternates, each joined to the origin —
+     * three times over to answer a question about a filename. `siteRoutes`
+     * then does the whole thing again on every dev-server request that hits a
+     * generated file.
+     *
+     * Safe to hold because everything it reads is settled before this closure
+     * exists: `entries`, `localeMeta` and the origin are fixed for the life of
+     * a `Site`, and `alternatesFor` reads nothing else. A dev server picks up
+     * an edited route by importing the module again and getting a *new* site,
+     * not by this one answering differently — so there is nothing here for a
+     * cache to go stale against.
+     *
+     * Sharing the `Sitemap` itself is safe for the same reason, with one part
+     * that would not be: `staticPaths` maps a fresh array per call, which is
+     * what an SSG router demands of it.
+     */
+    let built: Sitemap | undefined;
     function sitemap(): Sitemap {
-        return buildSitemap<L, RouteId>({
+        if (built !== undefined) return built;
+        built = buildSitemap<L, RouteId>({
             siteUrl,
             name: config_.sitemap?.name ?? "sitemap.xml",
             entryLimit: config_.sitemap?.entryLimit,
@@ -227,6 +251,7 @@ export function createSite<
             localeMeta,
             alternatesFor,
         });
+        return built;
     }
 
     // Registry declaration order, filtered to what this project builds.
@@ -242,12 +267,24 @@ export function createSite<
         pathContext
     ) as readonly RouteEntry<L, RouteId>[];
 
-    // In prefix-everything mode no route owns `/`; the locale root stands in for
-    // it, provided some route actually claims that path.
+    // The page the site's root resolves to, wherever routing puts it: `/` when
+    // the default locale is unprefixed, `/en-US` when it is not. Undefined
+    // unless a route actually claims that path — nothing has to own the root.
     const localeRootPath = buildPath("", defaultLocale, pathContext);
-    const rootEntry = prefixDefaultLocale
-        ? entries.find((entry) => entry.path === localeRootPath)
-        : undefined;
+    const rootEntry = entries.find(
+        (entry) =>
+            entry.locale === defaultLocale && entry.path === localeRootPath
+    );
+
+    /**
+     * Every path this build serves.
+     *
+     * Read by `redirects()` twice over: to reject a stated rule that shadows a
+     * real page, and to keep an inferred one from doing the same.
+     */
+    const builtPaths: ReadonlySet<string> = new Set(
+        entries.map((entry) => entry.path)
+    );
 
     function staticPaths(param: string): StaticPath<L, RouteId>[] {
         const paths: StaticPath<L, RouteId>[] = entries.map((entry) => ({
@@ -450,55 +487,108 @@ export function createSite<
         return joinUrl(siteUrl, path);
     }
 
-    function redirects(
-        rules: readonly RedirectRule<RouteId, L>[]
-    ): readonly ResolvedRedirect[] {
-        // When every locale is prefixed, nothing owns `/` — so lib claims it,
-        // with a real 301 to the default locale's root.
+    /**
+     * The rules lib writes for itself, from the route table rather than from
+     * anything a project states.
+     *
+     * Both answer one question: which URL that this build publishes nothing at
+     * will be asked for anyway? Each is a path the design deliberately does not
+     * serve — the root the routing mode leaves unowned, and the page one that
+     * is not numbered — and a path nobody serves on purpose is still a path
+     * somebody types. Both are read off `entries`, so a retranslated slug or a
+     * switched-off page moves the rule with it instead of leaving one pointing
+     * at a 404.
+     *
+     * Two, and deliberately not a third per *page*: mirroring every URL a
+     * project builds is a rule per page, and with slugs translated per locale
+     * it is a rule per page per language — a file of hundreds against the 2000
+     * a host reads, for URLs nothing ever linked. See `NOT-BUILT.md`.
+     *
+     * Both permanent. Neither is a state that changes while the config stays as
+     * it is: page one will never live at `/page/1`, and the root will not move
+     * while `prefixDefaultLocale` is what it is.
+     */
+    function inferredRedirects(): readonly ResolvedRedirect[] {
+        const status = statusFor("permanent");
+
+        // One root is served and the other is not, and which is which is what
+        // `prefixDefaultLocale` decides: prefixed, the site answers on `/en-US`
+        // and nothing owns `/`; unprefixed, it answers on `/` and `/en-US` is a
+        // URL nobody built — the one people still type, having seen every other
+        // language wear its prefix. Whichever of the two this build does not
+        // serve is pointed at the one it does.
         //
         // A redirect rather than a page: a meta-refresh stub at `/` is a soft
         // redirect, which search engines follow slowly and weigh less, and it
         // costs a render before the reader goes anywhere. The two cannot both
         // exist, since a static host serves the file and the rule never fires —
-        // which is what `builtPaths` below rejects.
-        // Named by route id like any other rule, so the target is derived from
-        // the route table and follows a retranslated slug.
-        const root: readonly RedirectRule<RouteId, L>[] =
+        // which is what `builtPaths` rejects.
+        const root: readonly ResolvedRedirect[] =
             rootEntry === undefined
                 ? []
                 : [
                       {
-                          from: "/",
-                          to: {
-                              route: rootEntry.routeId,
-                              locale: rootEntry.locale,
-                          },
-                          // The root will never own a page again while every
-                          // locale is prefixed, which is what permanent means.
-                          kind: "permanent",
+                          from: prefixDefaultLocale ? "/" : `/${defaultLocale}`,
+                          to: rootEntry.path,
+                          status,
                       },
                   ];
 
+        // `/news/page/1` for every list that runs past one page, in every
+        // language it is published in — see `pageOneAlias` for who asks for it.
+        //
+        // Only a route that *has* a second page: `1` or omitted is an ordinary
+        // route, and `/about/page/1` is a URL nobody has had a reason to type.
+        // The alias for a list that once ran longer and no longer does is the
+        // one this misses, and it is not worth a rule per page of the site.
+        const pageOne = entries
+            .filter(
+                (entry) =>
+                    entry.page === 1 &&
+                    (resolved[entry.routeId]?.pages ?? 1) > 1
+            )
+            .map((entry) => ({
+                from: pageOneAlias(entry.path, entry.locale, pathContext),
+                to: entry.path,
+                status,
+            }));
+
+        return [...root, ...pageOne];
+    }
+
+    function redirects(
+        rules: readonly RedirectRule<RouteId, L>[]
+    ): readonly ResolvedRedirect[] {
+        const stated: readonly ResolvedRedirect[] = rules.map((rule) => ({
+            from: rule.from,
+            // Three kinds of target, told apart by shape: a string is external
+            // and passes through, `file` is served verbatim from `public/`, and
+            // a route is resolved to whatever URL it has in the locale asked
+            // for.
+            to: ((): string => {
+                if (typeof rule.to === "string") return rule.to;
+                if ("file" in rule.to) return rule.to.file;
+                return pathFor(rule.to.route, rule.to.locale ?? defaultLocale);
+            })(),
+            status: statusFor(rule.kind),
+        }));
+
+        const claimed = new Set(stated.map((rule) => rule.from));
+        const inferred = inferredRedirects().filter(
+            // Dropped rather than reported, both times, because neither is a
+            // mistake anyone made: a rule the project wrote for one of these
+            // paths is a decision and this is a default, and a page built at
+            // one of them is a page, which outranks a mirror of another page.
+            // The same clash among *stated* rules still throws below — there,
+            // both sides were written on purpose and only one can fire.
+            (rule) => !claimed.has(rule.from) && !builtPaths.has(rule.from)
+        );
+
         return buildRedirects({
-            // Every path this build serves, so a rule that shadows a real page
-            // is rejected rather than sitting dead in the file.
-            builtPaths: new Set(entries.map((entry) => entry.path)),
-            rules: [...root, ...rules].map((rule) => ({
-                from: rule.from,
-                // Three kinds of target, told apart by shape: a string is
-                // external and passes through, `file` is served verbatim from
-                // `public/`, and a route is resolved to whatever URL it has in
-                // the locale asked for.
-                to: ((): string => {
-                    if (typeof rule.to === "string") return rule.to;
-                    if ("file" in rule.to) return rule.to.file;
-                    return pathFor(
-                        rule.to.route,
-                        rule.to.locale ?? defaultLocale
-                    );
-                })(),
-                status: statusFor(rule.kind),
-            })),
+            // So a rule that shadows a real page is rejected rather than
+            // sitting dead in the file.
+            builtPaths,
+            rules: [...inferred, ...stated],
         });
     }