@geekity/cms 0.3.0 → 0.5.0

package/dist/web/sitemap.d.ts

@@ -0,0 +1,120 @@
+import type { ConditionalHeaders } from './negotiate.ts';
+/**
+ * Where the sitemap and the robots file live, and what goes in them.
+ *
+ * Both are fixed paths at the root of the site, which is the only place a
+ * crawler looks for them, so both are real routes rather than anything
+ * resolved from the content index — a document permalinked at `/sitemap.xml`
+ * cannot take the URL a search engine polls.
+ *
+ * This module writes the documents and answers the requests; the *contents* of
+ * the sitemap — which URLs the site publishes — are assembled in
+ * `routes.ts`, where the listings, the archives and the permalinks are already
+ * spelled, so the sitemap cannot disagree with the site about where anything
+ * is.
+ */
+/** The sitemap's URL. Fixed: it is the one a `robots.txt` names. */
+export declare const SITEMAP_PATH = "/sitemap.xml";
+/** The robots file's URL. Fixed by the standard; nothing else is looked at. */
+export declare const ROBOTS_PATH = "/robots.txt";
+/** The namespace both a `<urlset>` and a `<sitemapindex>` are written in. */
+export declare const SITEMAP_NAMESPACE = "http://www.sitemaps.org/schemas/sitemap/0.9";
+/**
+ * How many URLs one sitemap file may hold before the site serves an index of
+ * several instead.
+ *
+ * The protocol's own ceiling. Its other ceiling is 50 MB uncompressed, which
+ * this one reaches first by a wide margin: an entry is a `<loc>` and a
+ * `<lastmod>`, on the order of 120 bytes, so a full file is nearer 6 MB than
+ * 50. Splitting on the count alone keeps one number to reason about.
+ */
+export declare const SITEMAP_MAX_URLS = 50000;
+/**
+ * The route pattern the child sitemaps are served under.
+ *
+ * How many children there are depends on how much the site has published, so
+ * they cannot be a list of literal routes; the pattern is fixed even though
+ * the set is not.
+ */
+export declare const SITEMAP_CHILD_ROUTE = "/sitemap-:page{[0-9]+}.xml";
+/** The URL of the nth child sitemap, counting from one. */
+export declare function sitemapChildPath(page: number): string;
+/** One entry: a URL the site publishes, and when it last changed. */
+export interface SitemapUrl {
+    /** The site-relative path, as the site itself spells it. */
+    loc: string;
+    /** When it last changed, or `undefined` when nothing dates it. */
+    lastmod?: Date | undefined;
+}
+/**
+ * A date as the sitemap protocol wants it: a W3C datetime.
+ *
+ * The milliseconds go, because nothing about a page changes within one and a
+ * crawler reads the field to the second at best.
+ */
+export declare function sitemapDate(date: Date): string;
+/** One `<urlset>` document over the URLs it is given. */
+export declare function sitemapXml(urls: readonly SitemapUrl[], baseUrl: string): string;
+/**
+ * One `<sitemapindex>` document naming the child sitemaps.
+ *
+ * Same shape as a `<urlset>` with a different element name around each entry,
+ * which is exactly what the protocol says the two documents are.
+ */
+export declare function sitemapIndexXml(children: readonly SitemapUrl[], baseUrl: string): string;
+/** What a sitemap is served as. */
+export declare const SITEMAP_CONTENT_TYPE = "application/xml; charset=utf-8";
+/** What a robots file is served as. */
+export declare const ROBOTS_CONTENT_TYPE = "text/plain; charset=utf-8";
+/** Everything one sitemap response needs. */
+export interface SitemapResponseOptions {
+    /** Every URL the site publishes, in the order the sitemap should list them. */
+    urls: readonly SitemapUrl[];
+    /** The site's public origin, for the absolute `<loc>`s. */
+    baseUrl: string;
+    /**
+     * Which child sitemap to serve, counting from one, or `undefined` for
+     * `/sitemap.xml` itself.
+     */
+    page?: number | undefined;
+    /** URLs per file. Defaults to {@link SITEMAP_MAX_URLS}. */
+    maxUrls?: number | undefined;
+    /** The request's conditional headers, for the 304. */
+    conditional?: ConditionalHeaders | undefined;
+}
+/**
+ * One sitemap as an HTTP response, or `undefined` when the URL names a child
+ * that does not exist and the caller owes a 404.
+ *
+ * `/sitemap.xml` is the whole thing while it fits, and an index naming the
+ * children once it does not — a crawler that holds the URL keeps it either
+ * way, which is the point of the index living at the same address.
+ *
+ * The validators are built before the conditional is decided, exactly as the
+ * feeds do it, so a crawler polling with `If-None-Match` still gets the ETag
+ * and the `Last-Modified` on the 304 it mostly receives.
+ */
+export declare function sitemapResponse(options: SitemapResponseOptions): Response | undefined;
+/**
+ * The robots file: everything public is crawlable, the admin is not, and the
+ * sitemap is named absolutely because that is the only spelling the standard
+ * allows for a `Sitemap:` line.
+ *
+ * Nothing else is disallowed. The ActivityPub routes under `/ap/` are left
+ * open deliberately: an actor and an object are documents meant to be
+ * fetched, they carry the same content as the pages that link to them, and a
+ * crawler that follows one gets JSON it will ignore. Hiding them would only
+ * make the fediverse's own view of the site depend on a file written for
+ * search engines.
+ */
+export declare function robotsTxt(baseUrl: string): string;
+/**
+ * The robots file as an HTTP response.
+ *
+ * It has a validator but no `Last-Modified`: nothing dates it. Its body is a
+ * function of the site's origin alone, so the ETag moves when that does and
+ * never otherwise, which is exactly what a crawler's `If-None-Match` should
+ * be told.
+ */
+export declare function robotsResponse(baseUrl: string, conditional?: ConditionalHeaders): Response;
+//# sourceMappingURL=sitemap.d.ts.map

package/dist/web/sitemap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sitemap.d.ts","sourceRoot":"","sources":["../../src/web/sitemap.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEzD;;;;;;;;;;;;;GAaG;AAEH,oEAAoE;AACpE,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C,+EAA+E;AAC/E,eAAO,MAAM,WAAW,gBAAgB,CAAC;AAEzC,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,gDAAgD,CAAC;AAE/E;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,QAAS,CAAC;AAEvC;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,+BAA+B,CAAC;AAEhE,2DAA2D;AAC3D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,qEAAqE;AACrE,MAAM,WAAW,UAAU;IACzB,4DAA4D;IAC5D,GAAG,EAAE,MAAM,CAAC;IACZ,kEAAkE;IAClE,OAAO,CAAC,EAAE,IAAI,GAAG,SAAS,CAAC;CAC5B;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAE9C;AAED,yDAAyD;AACzD,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,UAAU,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE/E;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,SAAS,UAAU,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAExF;AA2BD,mCAAmC;AACnC,eAAO,MAAM,oBAAoB,mCAAmC,CAAC;AAErE,uCAAuC;AACvC,eAAO,MAAM,mBAAmB,8BAA8B,CAAC;AAE/D,6CAA6C;AAC7C,MAAM,WAAW,sBAAsB;IACrC,+EAA+E;IAC/E,IAAI,EAAE,SAAS,UAAU,EAAE,CAAC;IAC5B,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,sDAAsD;IACtD,WAAW,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAC;CAC9C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,QAAQ,GAAG,SAAS,CA+BrF;AA2CD;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAQjD;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,kBAAkB,GAAG,QAAQ,CAW1F"}

package/dist/web/sitemap.js

@@ -0,0 +1,199 @@
+import { ADMIN_PREFIX } from '../admin/session.js';
+import { escapeXml } from './feeds.js';
+import { absoluteUrl, contentEtag, isNotModified } from './negotiate.js';
+/**
+ * Where the sitemap and the robots file live, and what goes in them.
+ *
+ * Both are fixed paths at the root of the site, which is the only place a
+ * crawler looks for them, so both are real routes rather than anything
+ * resolved from the content index — a document permalinked at `/sitemap.xml`
+ * cannot take the URL a search engine polls.
+ *
+ * This module writes the documents and answers the requests; the *contents* of
+ * the sitemap — which URLs the site publishes — are assembled in
+ * `routes.ts`, where the listings, the archives and the permalinks are already
+ * spelled, so the sitemap cannot disagree with the site about where anything
+ * is.
+ */
+/** The sitemap's URL. Fixed: it is the one a `robots.txt` names. */
+export const SITEMAP_PATH = '/sitemap.xml';
+/** The robots file's URL. Fixed by the standard; nothing else is looked at. */
+export const ROBOTS_PATH = '/robots.txt';
+/** The namespace both a `<urlset>` and a `<sitemapindex>` are written in. */
+export const SITEMAP_NAMESPACE = 'http://www.sitemaps.org/schemas/sitemap/0.9';
+/**
+ * How many URLs one sitemap file may hold before the site serves an index of
+ * several instead.
+ *
+ * The protocol's own ceiling. Its other ceiling is 50 MB uncompressed, which
+ * this one reaches first by a wide margin: an entry is a `<loc>` and a
+ * `<lastmod>`, on the order of 120 bytes, so a full file is nearer 6 MB than
+ * 50. Splitting on the count alone keeps one number to reason about.
+ */
+export const SITEMAP_MAX_URLS = 50_000;
+/**
+ * The route pattern the child sitemaps are served under.
+ *
+ * How many children there are depends on how much the site has published, so
+ * they cannot be a list of literal routes; the pattern is fixed even though
+ * the set is not.
+ */
+export const SITEMAP_CHILD_ROUTE = '/sitemap-:page{[0-9]+}.xml';
+/** The URL of the nth child sitemap, counting from one. */
+export function sitemapChildPath(page) {
+    return `/sitemap-${String(page)}.xml`;
+}
+/**
+ * A date as the sitemap protocol wants it: a W3C datetime.
+ *
+ * The milliseconds go, because nothing about a page changes within one and a
+ * crawler reads the field to the second at best.
+ */
+export function sitemapDate(date) {
+    return date.toISOString().replace(/\.\d+Z$/, 'Z');
+}
+/** One `<urlset>` document over the URLs it is given. */
+export function sitemapXml(urls, baseUrl) {
+    return document('urlset', urls, baseUrl, 'url');
+}
+/**
+ * One `<sitemapindex>` document naming the child sitemaps.
+ *
+ * Same shape as a `<urlset>` with a different element name around each entry,
+ * which is exactly what the protocol says the two documents are.
+ */
+export function sitemapIndexXml(children, baseUrl) {
+    return document('sitemapindex', children, baseUrl, 'sitemap');
+}
+/** Either sitemap document: the same entries under a different pair of names. */
+function document(root, entries, baseUrl, entryName) {
+    const lines = [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        `<${root} xmlns="${SITEMAP_NAMESPACE}">`,
+    ];
+    for (const entry of entries) {
+        lines.push(`  <${entryName}>`);
+        lines.push(`    <loc>${escapeXml(absoluteUrl(entry.loc, baseUrl))}</loc>`);
+        if (entry.lastmod !== undefined) {
+            lines.push(`    <lastmod>${sitemapDate(entry.lastmod)}</lastmod>`);
+        }
+        lines.push(`  </${entryName}>`);
+    }
+    lines.push(`</${root}>`, '');
+    return lines.join('\n');
+}
+/** What a sitemap is served as. */
+export const SITEMAP_CONTENT_TYPE = 'application/xml; charset=utf-8';
+/** What a robots file is served as. */
+export const ROBOTS_CONTENT_TYPE = 'text/plain; charset=utf-8';
+/**
+ * One sitemap as an HTTP response, or `undefined` when the URL names a child
+ * that does not exist and the caller owes a 404.
+ *
+ * `/sitemap.xml` is the whole thing while it fits, and an index naming the
+ * children once it does not — a crawler that holds the URL keeps it either
+ * way, which is the point of the index living at the same address.
+ *
+ * The validators are built before the conditional is decided, exactly as the
+ * feeds do it, so a crawler polling with `If-None-Match` still gets the ETag
+ * and the `Last-Modified` on the 304 it mostly receives.
+ */
+export function sitemapResponse(options) {
+    const { urls, baseUrl, page } = options;
+    const maxUrls = options.maxUrls ?? SITEMAP_MAX_URLS;
+    const split = urls.length > maxUrls;
+    if (page !== undefined && (!split || page < 1 || page > chunkCount(urls.length, maxUrls))) {
+        return undefined;
+    }
+    const entries = page !== undefined
+        ? urls.slice((page - 1) * maxUrls, page * maxUrls)
+        : split
+            ? childEntries(urls, maxUrls)
+            : urls;
+    const body = page === undefined && split ? sitemapIndexXml(entries, baseUrl) : sitemapXml(entries, baseUrl);
+    const etag = contentEtag('sitemap', fingerprint(entries, baseUrl, page));
+    const lastModified = newest(entries);
+    const headers = new Headers({ etag, 'cache-control': 'no-cache' });
+    if (lastModified !== undefined)
+        headers.set('last-modified', lastModified.toUTCString());
+    if (isNotModified(options.conditional, etag, lastModified)) {
+        return new Response(null, { status: 304, headers });
+    }
+    headers.set('content-type', SITEMAP_CONTENT_TYPE);
+    return new Response(body, { headers });
+}
+/** How many child sitemaps a URL count needs. */
+function chunkCount(total, maxUrls) {
+    return Math.ceil(total / maxUrls);
+}
+/**
+ * The children an index names: one per chunk, each dated by the newest thing
+ * in it, so a crawler can skip a file whose contents it already has.
+ */
+function childEntries(urls, maxUrls) {
+    const children = [];
+    for (let index = 0; index < chunkCount(urls.length, maxUrls); index += 1) {
+        const chunk = urls.slice(index * maxUrls, (index + 1) * maxUrls);
+        children.push({ loc: sitemapChildPath(index + 1), lastmod: newest(chunk) });
+    }
+    return children;
+}
+/** The most recent `lastmod` among some entries, if any has one. */
+function newest(entries) {
+    let latest;
+    for (const entry of entries) {
+        if (entry.lastmod === undefined)
+            continue;
+        if (latest === undefined || entry.lastmod > latest)
+            latest = entry.lastmod;
+    }
+    return latest;
+}
+/** What a sitemap document is made of, as one string to hash. */
+function fingerprint(entries, baseUrl, page) {
+    return [
+        baseUrl,
+        page === undefined ? 'index' : String(page),
+        ...entries.map((entry) => `${entry.loc} ${entry.lastmod?.toISOString() ?? ''}`),
+    ].join('\n');
+}
+/**
+ * The robots file: everything public is crawlable, the admin is not, and the
+ * sitemap is named absolutely because that is the only spelling the standard
+ * allows for a `Sitemap:` line.
+ *
+ * Nothing else is disallowed. The ActivityPub routes under `/ap/` are left
+ * open deliberately: an actor and an object are documents meant to be
+ * fetched, they carry the same content as the pages that link to them, and a
+ * crawler that follows one gets JSON it will ignore. Hiding them would only
+ * make the fediverse's own view of the site depend on a file written for
+ * search engines.
+ */
+export function robotsTxt(baseUrl) {
+    return [
+        'User-agent: *',
+        `Disallow: ${ADMIN_PREFIX}/`,
+        '',
+        `Sitemap: ${absoluteUrl(SITEMAP_PATH, baseUrl)}`,
+        '',
+    ].join('\n');
+}
+/**
+ * The robots file as an HTTP response.
+ *
+ * It has a validator but no `Last-Modified`: nothing dates it. Its body is a
+ * function of the site's origin alone, so the ETag moves when that does and
+ * never otherwise, which is exactly what a crawler's `If-None-Match` should
+ * be told.
+ */
+export function robotsResponse(baseUrl, conditional) {
+    const body = robotsTxt(baseUrl);
+    const etag = contentEtag('robots', body);
+    const headers = new Headers({ etag, 'cache-control': 'no-cache' });
+    if (isNotModified(conditional, etag, undefined)) {
+        return new Response(null, { status: 304, headers });
+    }
+    headers.set('content-type', ROBOTS_CONTENT_TYPE);
+    return new Response(body, { headers });
+}
+//# sourceMappingURL=sitemap.js.map

package/dist/web/sitemap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sitemap.js","sourceRoot":"","sources":["../../src/web/sitemap.ts"],"names":[],"mappings":"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"}

package/dist/web/taxonomy.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Where the taxonomy archives live, and how their URLs are spelled.
+ *
+ * The bases are a setting rather than a constant: a site moving off WordPress
+ * keeps `/tag/` and `/category/`, and a site that spells them otherwise says
+ * so on the settings screen. Everything that builds or parses one of those
+ * URLs — the public routes, the canonical redirects, the feeds, the theme, the
+ * ActivityStreams hashtags — goes through this module, so they cannot
+ * disagree about where an archive is.
+ */
+/** Where a paginated listing's later pages live, under any listing root. */
+export declare const PAGE_SEGMENT = "page";
+/** Which taxonomy an archive is over. */
+export type Taxonomy = 'tag' | 'category';
+/** Both taxonomies, in the order a screen or a loop should take them. */
+export declare const TAXONOMIES: readonly Taxonomy[];
+/** One archive: a taxonomy and the term whose documents it lists. */
+export interface TaxonomyTerm {
+    /** `tag` or `category`. */
+    taxonomy: Taxonomy;
+    /** The term itself, as the file spells it. */
+    term: string;
+}
+/** The URL segment each taxonomy's archives live under. */
+export type TaxonomyBases = Readonly<Record<Taxonomy, string>>;
+/**
+ * One term that was renamed, and what it was renamed to.
+ *
+ * A rename moves an archive, and an archive is a URL somebody may have linked
+ * to. The site records the move so the old URL can point at the new one for as
+ * long as it says so — a small list in the settings, and so in `site.json`,
+ * where an Eleventy build of the same content can publish the same redirects.
+ */
+export interface TaxonomyRedirect {
+    /** Which taxonomy's archive moved. */
+    taxonomy: Taxonomy;
+    /** The term that used to be there. */
+    from: string;
+    /** The term that is there now. */
+    to: string;
+}
+/**
+ * The bases a site has before anybody says otherwise: WordPress's own, so a
+ * site imported from it keeps every archive URL it had published.
+ */
+export declare const DEFAULT_TAXONOMY_BASES: TaxonomyBases;
+/** The word each taxonomy is called on a screen. */
+export declare const TAXONOMY_LABELS: Readonly<Record<Taxonomy, string>>;
+/**
+ * What a base may be made of: one path segment, starting with a letter or a
+ * digit, of at most 64 characters.
+ *
+ * Deliberately narrower than what a URL would carry. A base is the first
+ * segment of every archive URL the site publishes and the thing the router
+ * matches on, so it holds nothing that would need percent-encoding, nothing
+ * that could be read as a file extension, and no slash that would make it two
+ * segments.
+ */
+export declare const TAXONOMY_BASE_PATTERN: RegExp;
+/**
+ * Top-level paths the site already answers on, which a base may not take over.
+ *
+ * `feed` was here before anything served it: TASK-37 put the feeds at `/feed/`,
+ * and a site that had taken the word would find its archives shadowed by an
+ * upgrade. `comments` is the site-wide comments feed's root, for the same
+ * reason. `taxonomy.test.ts` pins this list against the prefixes those routes
+ * are actually registered under, so it cannot fall behind them.
+ *
+ * `sitemap.xml` and `robots.txt` are here because they are paths the site
+ * answers on, which is what the list is: {@link TAXONOMY_BASE_PATTERN} would
+ * refuse either of them anyway for the dot, so the entries are belt and
+ * braces rather than the only thing standing in the way.
+ *
+ * `author` and `inbox` are reserved harder than the rest (decision-14). Every
+ * user is an actor at `/author/{username}/` and the shared inbox is `/inbox/`,
+ * and an actor id is a name a follower's server has filed the account under:
+ * a base that took one of those words would not shadow an archive, it would
+ * unmake an account. `web/authors.ts` spells them as `AUTHOR_BASE` and
+ * `INBOX_BASE`, and `taxonomy.test.ts` holds this list against those two
+ * constants, so the reservation and the URLs cannot drift apart; they are
+ * literals here only because that module reads {@link PAGE_SEGMENT} from this
+ * one, and a cycle between two files of constants is not worth the tidiness.
+ */
+export declare const RESERVED_TOP_LEVEL_PATHS: readonly string[];
+/**
+ * The URL of a page of either taxonomy's archive, by zero-based index.
+ *
+ * This is the one place a taxonomy archive URL is spelled, so the routes, the
+ * pager, the canonical redirect, the theme links and the ActivityStreams
+ * hashtags cannot disagree about where an archive lives.
+ */
+export declare function termHref(term: TaxonomyTerm, index: number, bases: TaxonomyBases): string;
+/** The URL of a page of a tag archive, by zero-based index. */
+export declare function tagHref(tag: string, index: number, bases: TaxonomyBases): string;
+/** The URL of a page of a category archive, by zero-based index. */
+export declare function categoryHref(category: string, index: number, bases: TaxonomyBases): string;
+/** The taxonomy a first URL segment names, or `undefined` when it names none. */
+export declare function taxonomyForSegment(segment: string | undefined, bases: TaxonomyBases): Taxonomy | undefined;
+/** One message per base that cannot be used. An empty object is a valid pair. */
+export type TaxonomyBaseProblems = Partial<Record<Taxonomy, string>>;
+/**
+ * What is wrong with a pair of bases, one message per taxonomy.
+ *
+ * The pair is checked together rather than one at a time because two of the
+ * rules are about the pair: they may not be the same word, and neither may be
+ * a path the site already answers on.
+ */
+export declare function taxonomyBaseProblems(bases: TaxonomyBases): TaxonomyBaseProblems;
+/**
+ * A pair of bases as they should be stored: trimmed, and each replaced by its
+ * default when it is not usable. Only for reading a value back out of storage
+ * or a data file, where a bad value should not take the site down; a value on
+ * its way in goes through {@link taxonomyBaseProblems} and is refused.
+ */
+export declare function taxonomyBasesOrDefault(bases: Partial<Record<Taxonomy, unknown>>): TaxonomyBases;
+/**
+ * The recorded renames after one more, with chains collapsed.
+ *
+ * Three rules, all of them about not making a browser walk a history it does
+ * not care about. Anything that pointed at `from` is repointed at `to`, so
+ * `a → b` followed by `b → c` is stored as `a → c` and answered in one hop. An
+ * older record of `from` moving somewhere else is replaced, because it is no
+ * longer true. And any record of `to` having moved away is dropped, because
+ * the term is back and an archive that answers always beats a record of where
+ * it used to be.
+ */
+export declare function recordTermRename(existing: readonly TaxonomyRedirect[], change: TaxonomyRedirect): TaxonomyRedirect[];
+/**
+ * The recorded renames after a term is deleted.
+ *
+ * Every record pointing at it goes: the archive it named is about to 404, and
+ * a redirect to a 404 costs a round trip and tells the reader nothing. So does
+ * any record of that term having moved, which the delete has just settled.
+ */
+export declare function forgetTerm(existing: readonly TaxonomyRedirect[], taxonomy: Taxonomy, term: string): TaxonomyRedirect[];
+/**
+ * Where a term went, or `undefined` when nothing says it went anywhere.
+ *
+ * One hop, deliberately: the list is written with its chains already collapsed
+ * ({@link recordTermRename}), and following it further would let a hand-edited
+ * `site.json` send a reader round a loop.
+ */
+export declare function redirectedTerm(redirects: readonly TaxonomyRedirect[], term: TaxonomyTerm): string | undefined;
+/**
+ * A value out of `site.json` or a stored setting as the renames it names.
+ *
+ * Tolerant, like everything that reads that file: an entry that is not a
+ * `{ taxonomy, from, to }` of three non-empty strings is dropped rather than
+ * failing the read, and so is one that redirects a term to itself.
+ */
+export declare function taxonomyRedirectsOf(value: unknown): TaxonomyRedirect[];
+//# sourceMappingURL=taxonomy.d.ts.map

package/dist/web/taxonomy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"taxonomy.d.ts","sourceRoot":"","sources":["../../src/web/taxonomy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,4EAA4E;AAC5E,eAAO,MAAM,YAAY,SAAS,CAAC;AAEnC,yCAAyC;AACzC,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,UAAU,CAAC;AAE1C,yEAAyE;AACzE,eAAO,MAAM,UAAU,EAAE,SAAS,QAAQ,EAAwB,CAAC;AAEnE,qEAAqE;AACrE,MAAM,WAAW,YAAY;IAC3B,2BAA2B;IAC3B,QAAQ,EAAE,QAAQ,CAAC;IACnB,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,2DAA2D;AAC3D,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC;AAE/D;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,sCAAsC;IACtC,QAAQ,EAAE,QAAQ,CAAC;IACnB,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,aAGpC,CAAC;AAEF,oDAAoD;AACpD,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAG9D,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,QAAqC,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,wBAAwB,EAAE,SAAS,MAAM,EAarD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,MAAM,CAGxF;AAED,+DAA+D;AAC/D,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,MAAM,CAEhF;AAED,oEAAoE;AACpE,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,MAAM,CAE1F;AAED,iFAAiF;AACjF,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,KAAK,EAAE,aAAa,GACnB,QAAQ,GAAG,SAAS,CAMtB;AAED,iFAAiF;AACjF,MAAM,MAAM,oBAAoB,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC;AAErE;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,aAAa,GAAG,oBAAoB,CA+B/E;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,GAAG,aAAa,CAgB/F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,SAAS,gBAAgB,EAAE,EACrC,MAAM,EAAE,gBAAgB,GACvB,gBAAgB,EAAE,CAcpB;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,QAAQ,EAAE,SAAS,gBAAgB,EAAE,EACrC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,GACX,gBAAgB,EAAE,CAIpB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,SAAS,gBAAgB,EAAE,EACtC,IAAI,EAAE,YAAY,GACjB,MAAM,GAAG,SAAS,CAKpB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,EAAE,CAkBtE"}