@escape-game-over/atlas 0.1.1

package/src/url.ts

@@ -0,0 +1,144 @@
+/**
+ * URL shapes checked at the point they are written.
+ *
+ * Shared rather than restated, because more than one thing here takes a URL from
+ * a consumer — the site's own origin, and the target of an external redirect —
+ * and they must agree about what an acceptable one looks like. Each rejects with
+ * a named error rather than a bare pattern mismatch, so the message says what is
+ * wrong instead of only that something is.
+ */
+
+/**
+ * An absolute `https://` URL, as a shape.
+ *
+ * The plain type, for a URL that is *already* known good — what `createSite`
+ * hands back, and what a structured-data node quotes. The generic validators
+ * below are for a URL arriving from a consumer, where a named error is worth
+ * the type parameter; here there is nothing to explain, only a fact to keep.
+ *
+ * Sound because `createSite` throws on anything else before this is ever
+ * exposed. A type that outran its runtime check would be worse than none.
+ */
+export type HttpsUrl = `https://${string}`;
+
+/**
+ * The runtime half of `HttpsUrl`, written as a guard so the check that throws
+ * is also the check that narrows.
+ *
+ * A cast would assert the same thing without testing it, and would keep on
+ * asserting it after someone edited the condition above it.
+ */
+export function isHttpsUrl(url: string): url is HttpsUrl {
+    return url.startsWith("https://");
+}
+
+/**
+ * A path from the root of some origin: `/logo.png`, `/it/sfide`.
+ *
+ * The other half of every URL this library builds. Typed so a caller cannot
+ * hand over `logo.png` and get `https://example.comlogo.png`, which is the
+ * failure that reads as a typo in the output rather than as a bug in the join.
+ */
+export type UrlPath = `/${string}`;
+
+/** The runtime half of `UrlPath`. See `isHttpsUrl`. */
+export function isUrlPath(path: string): path is UrlPath {
+    return path.startsWith("/");
+}
+
+/**
+ * An origin without its trailing slash.
+ *
+ * Necessary because the *type* cannot rule one out — a template literal has no
+ * way to say "does not end in `/`" — so every origin arriving from outside is
+ * normalised rather than trusted. `https://x.example/` and `https://x.example`
+ * name the same origin, so this loses nothing and is not worth refusing over.
+ *
+ * It matters most where an origin becomes an identity: `https://x.example/`
+ * and `https://x.example` yield two different `@id` strings, and two
+ * deployments that wrote it differently would describe two separate brands.
+ */
+export function normalizeOrigin(origin: HttpsUrl): HttpsUrl {
+    if (!origin.endsWith("/")) return origin;
+    const trimmed = origin.slice(0, -1);
+    // Survives unless the whole value was `https://`, which is a scheme rather
+    // than an origin. Re-checking beats a cast asserting what was not tested.
+    if (!isHttpsUrl(trimmed)) {
+        throw new Error(`"${origin}" is a scheme, not an origin.`);
+    }
+    return trimmed;
+}
+
+/**
+ * An origin and a path, with exactly one slash between them.
+ *
+ * Every absolute URL lib emits is a concatenation, and both ends can carry a
+ * slash. Doing it by hand in a dozen places is how one of them ends up with
+ * `//` — which is a different URL, served or redirected inconsistently, and
+ * duplicate content if a crawler reaches both.
+ */
+export function joinUrl(origin: HttpsUrl, path: UrlPath): HttpsUrl {
+    return `${normalizeOrigin(origin)}${path}`;
+}
+
+export interface TrailingSlashNotAllowed<U extends string> {
+    readonly __URL_HAS_TRAILING_SLASH__: `url "${U}" must not end with a slash: every path lib builds already starts with one`;
+}
+
+export interface MustBeHttps<U extends string> {
+    readonly __URL_NOT_HTTPS__: `url "${U}" must start with https://: an http link is a downgrade, and browsers increasingly refuse it outright`;
+}
+
+/**
+ * An absolute `https://` URL. A path, query and trailing slash are all fine.
+ *
+ * For a URL that points *somewhere else* — the target of a redirect, say — where
+ * only the scheme is this library's business.
+ */
+export type ValidHttpsUrl<U extends string> = U extends `https://${string}`
+    ? U
+    : MustBeHttps<U>;
+
+/**
+ * Rejects an origin that is not a bare `https://` prefix without a trailing
+ * slash. A path is allowed, since deploying under a subdirectory is legitimate.
+ *
+ * Catches both at the point the URL is written, since a project states it as a
+ * literal. `createSite` still checks at build time, for the case where the URL
+ * comes from somewhere typed as plain `string` — an env var, say — and these
+ * checks pass vacuously.
+ */
+export type ValidSiteUrl<U extends string> = U extends `${string}/`
+    ? TrailingSlashNotAllowed<U>
+    : ValidHttpsUrl<U>;
+
+/**
+ * An asset's `src` as an absolute URL, whatever form it arrived in.
+ *
+ * Takes `string` because that is what a bundler declares `src` as, and turns it
+ * into one of the only two things it can legitimately be — an `https://` URL
+ * already, or a path on this origin.
+ *
+ * Neither rejection is pedantry. An `http://` asset is mixed content, dropped
+ * by anything that scrapes it. A relative `logo.png` would be joined as written
+ * and produce `https://example.comlogo.png`, which reads as a typo in the
+ * output long before anyone suspects the join.
+ *
+ * Throws rather than skipping, because the callers build *sets* — three crops
+ * of a photograph, one per aspect ratio — and quietly returning two of them is
+ * a set that looks complete and is not.
+ */
+export function absoluteUrl(
+    origin: HttpsUrl,
+    src: string,
+    at: string
+): HttpsUrl {
+    if (isHttpsUrl(src)) return src;
+
+    if (!isUrlPath(src)) {
+        throw new Error(
+            `${at}: "${src}" is neither an https:// URL nor a path from the root.`
+        );
+    }
+    return joinUrl(origin, src);
+}

package/src/warn.ts

@@ -0,0 +1,88 @@
+/**
+ * The one place lib writes to a console.
+ *
+ * Everything here is a *warning* by definition: a fact about a file or a string
+ * that no type can see, worth saying out loud but never worth failing a build
+ * over. Errors throw instead, and say so at the point they are wrong.
+ *
+ * Shared so the colouring and the `[lib]` prefix are decided once — a warning
+ * that looks different depending on which module raised it reads like two
+ * different tools.
+ */
+
+/**
+ * What every line lib writes is labelled with.
+ *
+ * A constant rather than a literal at each call site: grep for it to find every
+ * warning the library can raise, and change it once if this folder is ever
+ * published under its real name.
+ */
+const PREFIX = "lib";
+
+/**
+ * The escape character, named rather than embedded. 27 is its code point.
+ *
+ * The three constants below used to hold the raw control byte inside their
+ * string literals — invisible in every editor, and sitting in a folder whose
+ * whole purpose is to be copied between repositories, where a tool that
+ * normalises or re-encodes on the way through would take the colour with it
+ * silently and only in the copy.
+ *
+ * Built from the code point rather than from a unicode escape, which takes the
+ * same reasoning one step further: the source stays plain ASCII with nothing to
+ * mis-transcribe, and the constant says what the byte *is* rather than leaving
+ * a reader to decode it. Nothing in this file needs a character an editor
+ * cannot show.
+ */
+const ESC = String.fromCharCode(27);
+
+const YELLOW = `${ESC}[33m`;
+const DIM = `${ESC}[2m`;
+const RESET = `${ESC}[0m`;
+
+/**
+ * Whether to emit ANSI colour.
+ *
+ * `NO_COLOR` is the convention every CLI honours, and the check reaches through
+ * `globalThis` rather than naming `process`: this file is part of the core,
+ * which is type-checked with `"types": []` and cannot see Node. A browser has no
+ * `process` and simply gets colour, which is what a browser console renders
+ * anyway.
+ */
+const colour =
+    (
+        globalThis as {
+            process?: { env?: Readonly<Record<string, string | undefined>> };
+        }
+    ).process?.env?.NO_COLOR === undefined;
+
+const paint = (code: string, text: string): string =>
+    colour ? `${code}${text}${RESET}` : text;
+
+/**
+ * Warns about one page, or one file.
+ *
+ * `at` is whatever identifies the thing — a canonical URL, an asset path. It is
+ * always printed, because a warning nobody can locate is one nobody acts on.
+ */
+export function warn(at: string, message: string): void {
+    console.warn(
+        `${paint(YELLOW, `[${PREFIX}] [WARN]`)} ${paint(DIM, shorten(at))}\n  ${message}`
+    );
+}
+
+/**
+ * An absolute URL down to its path.
+ *
+ * Every warning in one build shares an origin, so printing it on each is the
+ * same forty characters repeated — and the path is what matches the page list
+ * the build is already printing beside it. Anything that is not a URL, such as
+ * a filename, is left as it is.
+ */
+function shorten(at: string): string {
+    try {
+        return new URL(at).pathname;
+    } catch {
+        return at;
+    }
+}

package/src/xml.ts

@@ -0,0 +1,103 @@
+/**
+ * A minimal XML element builder.
+ *
+ * Generating XML by concatenating template literals means hand-managing
+ * indentation, stray newlines and — worse — remembering to escape at every
+ * interpolation. Building a tree instead makes the shape of the document read
+ * like the document, and escaping happens once, in the renderer.
+ */
+
+const XML_ESCAPES: Readonly<Record<string, string>> = {
+    "&": "&amp;",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&apos;",
+};
+
+export function escapeXml(value: string): string {
+    return value.replace(/[&<>"']/g, (char) => XML_ESCAPES[char] ?? char);
+}
+
+export type XmlAttributes = Readonly<Record<string, string | undefined>>;
+
+export interface XmlElement {
+    readonly tag: string;
+    readonly attrs?: XmlAttributes;
+    readonly text?: string;
+    readonly children?: readonly XmlChild[];
+}
+
+/**
+ * `false` and `undefined` are allowed so conditional children read inline:
+ * `cond && el("priority", undefined, "1.0")`.
+ */
+export type XmlChild = XmlElement | false | undefined;
+
+export type XmlChildren = string | readonly XmlChild[];
+
+/**
+ * Builds an element. Attributes are optional and may be skipped entirely:
+ *
+ * ```ts
+ * el("loc", "https://example.com")                  // text
+ * el("url", [el("loc", "…")])                       // children
+ * el("xhtml:link", { rel: "alternate", href: "…" }) // attributes only
+ * el("urlset", { xmlns: "…" }, urls)                // both
+ * ```
+ */
+export function el(tag: string, children?: XmlChildren): XmlElement;
+export function el(
+    tag: string,
+    attrs: XmlAttributes,
+    children?: XmlChildren
+): XmlElement;
+export function el(
+    tag: string,
+    attrsOrChildren?: XmlAttributes | XmlChildren,
+    maybeChildren?: XmlChildren
+): XmlElement {
+    const isChildren =
+        typeof attrsOrChildren === "string" || Array.isArray(attrsOrChildren);
+    const attrs = isChildren ? undefined : (attrsOrChildren as XmlAttributes);
+    const children = isChildren
+        ? (attrsOrChildren as XmlChildren)
+        : maybeChildren;
+
+    return typeof children === "string"
+        ? { tag, attrs, text: children }
+        : { tag, attrs, children };
+}
+
+function renderAttrs(attrs: XmlAttributes | undefined): string {
+    if (attrs === undefined) return "";
+    return Object.entries(attrs)
+        .filter(([, value]) => value !== undefined)
+        .map(([name, value]) => ` ${name}="${escapeXml(value as string)}"`)
+        .join("");
+}
+
+/** Renders one element, indenting nested levels by two spaces. */
+export function renderXml(node: XmlElement, depth = 0): string {
+    const pad = "  ".repeat(depth);
+    const open = `${pad}<${node.tag}${renderAttrs(node.attrs)}`;
+
+    if (node.text !== undefined) {
+        return `${open}>${escapeXml(node.text)}</${node.tag}>`;
+    }
+
+    const children = (node.children ?? []).filter(
+        (child): child is XmlElement => child !== false && child !== undefined
+    );
+    if (children.length === 0) return `${open} />`;
+
+    const inner = children
+        .map((child) => renderXml(child, depth + 1))
+        .join("\n");
+    return `${open}>\n${inner}\n${pad}</${node.tag}>`;
+}
+
+/** Renders a whole document, declaration included, with a trailing newline. */
+export function renderXmlDocument(root: XmlElement): string {
+    return `<?xml version="1.0" encoding="UTF-8"?>\n${renderXml(root)}\n`;
+}