forgebook 0.1.7 → 0.2.0

package/dist/src/vite/docMarkdown.js

@@ -0,0 +1,150 @@
+/**
+ * What every docs page and the written home go through before their blocks: the front matter, the Markdown reader with
+ * the page's own inline syntax (a value in double braces, `{{components}}`), and the page's title.
+ *
+ * @remarks
+ * A value is a token of its own, read by the same lexer as the rest of the text, so it is never read inside code: a
+ * fence or a code span shows `{{title}}` as written, which is how a page documents the syntax itself. Pure.
+ *
+ * @module
+ */
+import { basename } from "node:path";
+import { Marked } from "marked";
+import { PAGE_VALUES, valueMark } from "../docPages.js";
+import { storyName } from "../storyTree.js";
+import { escapeHtml } from "./highlightCode.js";
+/** The line a front matter starts and ends with. */
+const FENCE = "---";
+/** The keys a front matter can hold. */
+const FRONT_MATTER_KEYS = ["title", "order", "description"];
+/** A value without its surrounding quotes. */
+const unquoted = (value) => {
+    const first = value.at(0);
+    return value.length > 1 && (first === '"' || first === "'") && value.endsWith(first)
+        ? value.slice(1, -1)
+        : value;
+};
+/**
+ * A page's text split at its front matter: `key: value` lines between two `---` lines, the file's very first line
+ * the opening one.
+ *
+ * @remarks
+ * Only three plain keys, so no YAML parser joins the core's dependencies; a key it does not know is reported, since a
+ * typo would otherwise leave a page silently out of its place.
+ *
+ * @param text - the file's text.
+ */
+export const frontMatterOf = (text) => {
+    const lines = text.replace(/^/, "").split(/\r?\n/);
+    const none = { title: undefined, order: undefined, description: undefined, bodyLine: 1 };
+    if (lines[0]?.trim() !== FENCE)
+        return { ...none, body: lines.join("\n"), notes: [] };
+    const end = lines.findIndex((line, index) => index > 0 && line.trim() === FENCE);
+    if (end === -1)
+        return { ...none, body: lines.join("\n"), notes: [{ line: 1, message: "its front matter never ends" }] };
+    const notes = [];
+    const fields = new Map();
+    lines.slice(1, end).forEach((line, index) => {
+        if (line.trim() === "" || line.trimStart().startsWith("#"))
+            return;
+        const colon = line.indexOf(":");
+        const key = line.slice(0, colon).trim();
+        if (colon === -1 || !FRONT_MATTER_KEYS.includes(key)) {
+            notes.push({
+                line: index + 2,
+                message: `its front matter has a line it does not read: "${line.trim()}"`
+            });
+            return;
+        }
+        fields.set(key, { value: unquoted(line.slice(colon + 1).trim()), line: index + 2 });
+    });
+    const orderField = fields.get("order");
+    const order = orderField === undefined || orderField.value === "" ? undefined : Number(orderField.value);
+    if (orderField !== undefined && order !== undefined && !Number.isFinite(order))
+        notes.push({ line: orderField.line, message: `its order "${orderField.value}" is not a number` });
+    return {
+        body: lines.slice(end + 1).join("\n"),
+        bodyLine: end + 2,
+        title: fields.get("title")?.value || undefined,
+        order: order !== undefined && Number.isFinite(order) ? order : undefined,
+        description: fields.get("description")?.value || undefined,
+        notes
+    };
+};
+/**
+ * Whether a token is a value.
+ *
+ * @param token - the token.
+ */
+export const isValueToken = (token) => token.type === "value" && typeof token["name"] === "string" && typeof token["text"] === "string";
+/**
+ * Whether a name is one of the values a page can name.
+ *
+ * @param name - the name.
+ */
+export const isPageValue = (name) => PAGE_VALUES.some((value) => value === name);
+/** A value in double braces: `{{components}}`, spaces inside allowed. */
+const VALUE = /^\{\{\s*([A-Za-z][\w-]*)\s*\}\}/;
+/**
+ * The inline syntax of a page's values: read as a token, drawn as its build-time text (`version`) or as the mark the
+ * shell fills; a name the page cannot use stays as written, and the page's checks report it.
+ */
+export const VALUES_EXTENSION = {
+    extensions: [
+        {
+            name: "value",
+            level: "inline",
+            start: (source) => {
+                const at = source.indexOf("{{");
+                return at === -1 ? undefined : at;
+            },
+            tokenizer: (source) => {
+                const match = VALUE.exec(source);
+                return match?.[1] === undefined
+                    ? undefined
+                    : { type: "value", raw: match[0], name: match[1], text: match[0] };
+            },
+            renderer: (token) => {
+                if (!isValueToken(token) || !isPageValue(token.name))
+                    return escapeHtml(token.raw);
+                return token.name === "version" ? escapeHtml(token.text) : valueMark(token.name);
+            }
+        }
+    ]
+};
+/** A reader of a page's tokens: nothing rendered. */
+export const LEXER = new Marked({ async: false, gfm: true }, VALUES_EXTENSION);
+/** The first token that is not blank space. */
+export const firstToken = (tokens) => tokens.find((token) => token.type !== "space");
+/** A file name as a page's title: `getting-started.md` → "Getting started". */
+const titleFromFile = (file) => storyName(basename(file, ".md").replace(/[-_]+/g, " "));
+/**
+ * A page's title: its front matter's, else its opening `#` heading, else its file's name.
+ *
+ * @param file - the page's file.
+ * @param frontMatter - its front matter.
+ */
+export const titleOf = (file, frontMatter) => {
+    if (frontMatter.title !== undefined)
+        return frontMatter.title;
+    const heading = openingHeading(LEXER.lexer(frontMatter.body));
+    return heading ?? titleFromFile(file);
+};
+/**
+ * The text of a page's opening `#` heading; none when it opens with something else.
+ *
+ * @param tokens - the page's tokens.
+ */
+export const openingHeading = (tokens) => {
+    const first = firstToken(tokens);
+    return first?.type === "heading" && first["depth"] === 1 && typeof first["text"] === "string"
+        ? first["text"]
+        : undefined;
+};
+/** The tokens without the page's opening `#` title: the page's header shows the title. */
+export const withoutTitle = (tokens) => {
+    const first = firstToken(tokens);
+    return first?.type === "heading" && first["depth"] === 1
+        ? tokens.filter((token) => token !== first)
+        : tokens;
+};

package/dist/src/vite/docPageBlocks.d.ts

@@ -0,0 +1,64 @@
+/**
+ * A docs page read into its blocks, before any HTML: each directive given its meaning, each fence its kind, each link
+ * and image checked and addressed, and everything wrong noted with its line and column.
+ *
+ * @remarks
+ * One reading serves both the index (what the sidebar and the checks need, nothing rendered) and the page itself
+ * (`docPageRender.ts` turns the nodes into HTML), so the two never disagree about what a page holds or gets wrong. The
+ * names a page can use are fixed here: asides by tone, `tabs`, `steps`, `cards`, `card` and `link-card`, and on the
+ * written home the pieces of today's home. A block that cannot be read keeps its content as text and is reported, so a
+ * mistake never blanks a page.
+ *
+ * @module
+ */
+import type { Token } from "marked";
+import { type AsideTone, type HomePiece } from "../docPages.ts";
+import { type BodySegment } from "./docDirectives.ts";
+import { type PageReading } from "./docPageTokens.ts";
+/** A piece of a page read, before its HTML. */
+export type PageNode = {
+    readonly type: "tokens";
+    readonly tokens: readonly Token[];
+} | {
+    readonly type: "aside";
+    readonly tone: AsideTone;
+    readonly title?: string;
+    readonly children: PageNode[];
+} | {
+    readonly type: "tabs";
+    readonly sync?: string;
+    readonly tabs: readonly {
+        readonly label: string;
+        readonly children: PageNode[];
+    }[];
+} | {
+    readonly type: "steps";
+    readonly steps: readonly (readonly Token[])[];
+} | {
+    readonly type: "cards";
+    readonly children: PageNode[];
+} | {
+    readonly type: "card";
+    readonly title: string;
+    readonly children: PageNode[];
+} | {
+    readonly type: "link-card";
+    readonly title: string;
+    readonly href: string;
+    readonly description?: string;
+} | {
+    readonly type: "home";
+    readonly piece: HomePiece;
+    readonly label?: string;
+    readonly source?: string;
+} | {
+    readonly type: "problem";
+    readonly message: string;
+};
+/**
+ * A page's segments read into its nodes.
+ *
+ * @param segments - the page's segments.
+ * @param reading - the reading.
+ */
+export declare const pageNodes: (segments: readonly BodySegment[], reading: PageReading) => PageNode[];

package/dist/src/vite/docPageBlocks.js

@@ -0,0 +1,322 @@
+import { ASIDE_TONES, HOME_PIECES } from "../docPages.js";
+import { noteText } from "./docDirectives.js";
+import { isPageValue } from "./docMarkdown.js";
+import { isPageLink, linkedSlug, pageAddress } from "./docPageLinks.js";
+import { isOrderedList, lexed, positionsOf, readTokens } from "./docPageTokens.js";
+/** The tone each GitHub alert takes: its warning is a caution, its caution a danger, as their colours say. */
+const ALERT_TONES = {
+    NOTE: "note",
+    TIP: "tip",
+    IMPORTANT: "important",
+    WARNING: "caution",
+    CAUTION: "danger"
+};
+/** The names of the blocks a page can write, for the note about one it cannot. */
+const KNOWN_BLOCKS = [...ASIDE_TONES, "tabs", "tab", "steps", "cards", "card"].map((name) => `:::${name}`);
+/** The leaf blocks a page can write, for the same note. */
+const KNOWN_LEAVES = ["link-card", ...HOME_PIECES].map((name) => `::${name}`);
+/** The pieces of the home that take a heading of their own. */
+const LABELLED_PIECES = ["recent", "families", "pages"];
+/** The addresses a link card may open: another site, or an address of the catalogue; never `//host` or `/\host`, another site in disguise. */
+const CARD_ADDRESS = /^(https?:|mailto:|\?|#|\/(?![/\\]))/i;
+/** The asides other tools name otherwise, by those names. */
+const OTHER_NAMES = {
+    warning: "caution",
+    info: "note",
+    error: "danger",
+    success: "tip"
+};
+/** A hint at the aside another tool's name means, for the note about it; empty for any other name. */
+const similarTo = (name) => {
+    const tone = OTHER_NAMES[name];
+    return tone === undefined ? "" : ` (for this aside, write \`:::${tone}\`)`;
+};
+/** Whether a tone is an aside's. */
+const isTone = (name) => ASIDE_TONES.some((tone) => tone === name);
+/** Whether a name is a piece of the home. */
+const isHomePiece = (name) => HOME_PIECES.some((piece) => piece === name);
+/** Whether a segment is Markdown with nothing in it. */
+const isBlank = (segment) => segment.type === "markdown" && segment.lines.every((line) => line.text.trim() === "");
+/** Where a segment starts. */
+const segmentPosition = (segment) => {
+    if (segment.type === "container" || segment.type === "leaf")
+        return segment.directive.position;
+    if (segment.type === "alert")
+        return segment.position;
+    const line = segment.lines.find((each) => each.text.trim() !== "") ?? segment.lines[0];
+    return line === undefined ? { line: 1, column: 1 } : { line: line.line, column: line.column };
+};
+/** Notes a directive's attributes beyond those its block takes. */
+const checkAttributes = (directive, allowed, reading) => {
+    for (const [key, { position }] of directive.attributes) {
+        if (allowed.includes(key))
+            continue;
+        const takes = allowed.length === 0 ? "it takes none" : `it takes ${allowed.map((each) => `"${each}"`).join(", ")}`;
+        reading.notes.push({ position, message: `\`${directive.name}\` has no attribute "${key}": ${takes}` });
+    }
+};
+/** A directive's attribute's value; none when it does not have it. */
+const attributeOf = (directive, key) => directive.attributes.get(key)?.value;
+/**
+ * A directive's label as plain text: `{{version}}` written in, another value kept for the shell to fill, a name no
+ * page can use reported.
+ */
+const labelText = (directive, reading) => {
+    const { label, labelPosition } = directive;
+    return label === undefined ? undefined : valuesIn(label, labelPosition, reading);
+};
+/**
+ * A plain text of a block (its label, a card's description) with `{{version}}` written in, another value kept for the
+ * shell to fill, and a name no page can use reported.
+ *
+ * @param text - the text.
+ * @param start - where it starts, for the notes; none when unknown.
+ * @param reading - the reading.
+ */
+const valuesIn = (text, start, reading) => text.replace(/\{\{\s*([A-Za-z][\w-]*)\s*\}\}/g, (written, name, offset) => {
+    if (!isPageValue(name)) {
+        if (start !== undefined)
+            reading.notes.push({
+                position: { line: start.line, column: start.column + offset },
+                message: `\`${written}\` is not a value a page can show`
+            });
+        return written;
+    }
+    return name === "version" ? (reading.version() ?? "") : written;
+});
+/** A Markdown segment read. */
+const markdownNode = (lines, reading) => {
+    const { text, tokens } = lexed(lines);
+    readTokens(tokens, text, 0, positionsOf(lines), reading);
+    return { type: "tokens", tokens };
+};
+/** The segments of a container read, blank Markdown left out. */
+const nodesOf = (segments, reading) => segments.flatMap((segment) => (isBlank(segment) ? [] : segmentNodes(segment, reading)));
+/** A `tabs` block read: its `:::tab` blocks, anything else reported. */
+const tabsNode = (directive, children, reading) => {
+    checkAttributes(directive, ["syncKey"], reading);
+    const tabs = [];
+    for (const child of children) {
+        if (isBlank(child))
+            continue;
+        if (child.type !== "container" || child.directive.name !== "tab") {
+            reading.notes.push({
+                position: segmentPosition(child),
+                message: `only \`:::tab\` blocks go in \`tabs\` (line ${directive.position.line}): this is left out`
+            });
+            continue;
+        }
+        checkAttributes(child.directive, [], reading);
+        const label = labelText(child.directive, reading);
+        if (label === undefined || label.trim() === "")
+            reading.notes.push({
+                position: child.directive.position,
+                message: "a tab needs its label: `:::tab[npm]`"
+            });
+        tabs.push({
+            label: label?.trim() || String(tabs.length + 1),
+            children: nodesOf(child.children, reading)
+        });
+    }
+    if (tabs.length === 0)
+        reading.notes.push({ position: directive.position, message: "`tabs` holds no `:::tab`" });
+    const sync = attributeOf(directive, "syncKey");
+    return { type: "tabs", ...(sync === undefined || sync === "" ? {} : { sync }), tabs };
+};
+/** A `steps` block read: one ordered list, each item a step; anything else drawn as it is, and reported. */
+const stepsNodes = (directive, children, reading) => {
+    checkAttributes(directive, [], reading);
+    const filled = children.filter((child) => !isBlank(child));
+    const only = filled[0];
+    if (filled.length === 1 && only?.type === "markdown") {
+        const { text, tokens } = lexed(only.lines);
+        const content = tokens.filter((token) => token.type !== "space");
+        const list = content[0];
+        if (content.length === 1 && isOrderedList(list)) {
+            const at = positionsOf(only.lines);
+            const listStart = Math.max(0, text.indexOf(list.raw));
+            let cursor = 0;
+            const steps = list.items.map((item) => {
+                const place = list.raw.indexOf(item.raw, cursor);
+                cursor = place === -1 ? cursor : place;
+                readTokens(item.tokens, item.raw, listStart + cursor, at, reading);
+                return item.tokens;
+            });
+            return [{ type: "steps", steps }];
+        }
+    }
+    reading.notes.push({
+        position: directive.position,
+        message: "`steps` holds one numbered list, each item a step: this one is drawn as it is"
+    });
+    return nodesOf(children, reading);
+};
+/** A `cards` block read: its cards, anything else reported and drawn as it is. */
+const cardsNode = (directive, children, reading) => {
+    checkAttributes(directive, [], reading);
+    for (const child of children) {
+        if (isBlank(child))
+            continue;
+        const isCard = (child.type === "container" && child.directive.name === "card") ||
+            (child.type === "leaf" && child.directive.name === "link-card");
+        if (!isCard)
+            reading.notes.push({
+                position: segmentPosition(child),
+                message: "only `:::card` and `::link-card` blocks go in `cards`"
+            });
+    }
+    return { type: "cards", children: nodesOf(children, reading) };
+};
+/** A link card's address checked: another page by its file, an address of the catalogue, or another site. */
+const cardAddress = (href, position, reading) => {
+    if (isPageLink(href)) {
+        const address = pageAddress(reading.file, href, reading.read);
+        if (address === undefined) {
+            reading.notes.push({ position, message: `the card links to "${href}", which is not there` });
+            return undefined;
+        }
+        const slug = linkedSlug(reading.file, href, reading.read);
+        if (slug !== undefined)
+            reading.links.push(slug);
+        return address;
+    }
+    if (CARD_ADDRESS.test(href))
+        return href;
+    reading.notes.push({
+        position,
+        message: `the card's "${href}" is no page or address: link a page's file, an address of the catalogue (?component=…) or a site`
+    });
+    return undefined;
+};
+/** A problem said in place, and noted. */
+const problemAt = (position, message, reading) => {
+    const note = { position, message };
+    reading.notes.push(note);
+    return [{ type: "problem", message: noteText(note) }];
+};
+/** A link card read: its title, its address checked, its description. */
+const linkCardNodes = (directive, reading) => {
+    const { position } = directive;
+    checkAttributes(directive, ["href", "description"], reading);
+    const title = labelText(directive, reading)?.trim() ?? "";
+    const written = attributeOf(directive, "href") ?? "";
+    if (title === "" || written === "")
+        return problemAt(position, 'a link card needs a title and an address: `::link-card[Theming]{href="./theming.md"}`', reading);
+    const href = cardAddress(written, directive.attributes.get("href")?.position ?? position, reading);
+    if (href === undefined)
+        return [];
+    const described = directive.attributes.get("description");
+    const description = described === undefined ? undefined : valuesIn(described.value, described.valuePosition, reading);
+    return [{ type: "link-card", title, href, ...(description === undefined ? {} : { description }) }];
+};
+/** A piece of the home read: drawn on the written home only, reported anywhere else. */
+const homePieceNodes = (piece, directive, reading) => {
+    const { position } = directive;
+    if (!reading.isHome)
+        return problemAt(position, `\`::${piece}\` is drawn only on the catalogue's home`, reading);
+    checkAttributes(directive, piece === "recent" ? [] : ["source"], reading);
+    const isLabelled = LABELLED_PIECES.includes(piece);
+    const label = labelText(directive, reading);
+    if (label !== undefined && !isLabelled)
+        reading.notes.push({
+            position,
+            message: `\`::${piece}\` takes no label: each library has its own heading`
+        });
+    const source = piece === "recent" ? undefined : attributeOf(directive, "source");
+    if (source !== undefined)
+        reading.sources.push(source);
+    return [
+        {
+            type: "home",
+            piece,
+            ...(label === undefined || !isLabelled ? {} : { label }),
+            ...(source === undefined ? {} : { source })
+        }
+    ];
+};
+/** A leaf directive read. */
+const leafNodes = (directive, reading) => {
+    const { name, position } = directive;
+    if (name === "link-card")
+        return linkCardNodes(directive, reading);
+    if (isHomePiece(name))
+        return homePieceNodes(name, directive, reading);
+    if (isTone(name) || ["tabs", "tab", "steps", "cards", "card"].includes(name))
+        return problemAt(position, `\`::${name}\` is a block that holds others: write \`:::${name}\`, then a line of \`:::\``, reading);
+    reading.notes.push({
+        position,
+        message: `\`::${name}\` is not a block Forgebook knows: ${KNOWN_LEAVES.join(", ")}; or a container, ${KNOWN_BLOCKS.join(", ")}; it stays as text`
+    });
+    return [markdownNode([directive.line], reading)];
+};
+/** A container directive read. */
+const containerNodes = (directive, children, reading) => {
+    const { name, position } = directive;
+    if (isTone(name)) {
+        checkAttributes(directive, [], reading);
+        const title = labelText(directive, reading)?.trim();
+        return [{ type: "aside", tone: name, ...(title ? { title } : {}), children: nodesOf(children, reading) }];
+    }
+    switch (name) {
+        case "tabs":
+            return [tabsNode(directive, children, reading)];
+        case "steps":
+            return stepsNodes(directive, children, reading);
+        case "cards":
+            return [cardsNode(directive, children, reading)];
+        case "card": {
+            checkAttributes(directive, [], reading);
+            const title = labelText(directive, reading)?.trim() ?? "";
+            if (title === "")
+                reading.notes.push({ position, message: "a card needs its title: `:::card[Install]`" });
+            return [{ type: "card", title, children: nodesOf(children, reading) }];
+        }
+        case "tab":
+            reading.notes.push({
+                position,
+                message: "`:::tab` goes inside `::::tabs`: its content is drawn as it is"
+            });
+            return nodesOf(children, reading);
+        default: {
+            const isLeaf = name === "link-card" || isHomePiece(name);
+            reading.notes.push({
+                position,
+                message: isLeaf
+                    ? `\`${name}\` stands alone: write \`::${name}\` on one line, with no closing line`
+                    : `\`:::${name}\` is not a block Forgebook knows${similarTo(name)}: ${KNOWN_BLOCKS.join(", ")}; its content is drawn as it is`
+            });
+            return nodesOf(children, reading);
+        }
+    }
+};
+/**
+ * A segment of a page read into its nodes.
+ *
+ * @param segment - the segment.
+ * @param reading - the reading.
+ */
+const segmentNodes = (segment, reading) => {
+    switch (segment.type) {
+        case "markdown":
+            return [markdownNode(segment.lines, reading)];
+        case "alert":
+            return [
+                {
+                    type: "aside",
+                    tone: ALERT_TONES[segment.kind] ?? "note",
+                    children: nodesOf(segment.children, reading)
+                }
+            ];
+        case "leaf":
+            return leafNodes(segment.directive, reading);
+        default:
+            return containerNodes(segment.directive, segment.children, reading);
+    }
+};
+/**
+ * A page's segments read into its nodes.
+ *
+ * @param segments - the page's segments.
+ * @param reading - the reading.
+ */
+export const pageNodes = (segments, reading) => nodesOf(segments, reading);

package/dist/src/vite/docPageLinks.d.ts

@@ -0,0 +1,72 @@
+/** Reads a linked page's text: none when it is not there. */
+export type ReadPage = (file: string) => string | undefined;
+/**
+ * A linked page's text from the disk.
+ *
+ * @param file - the file.
+ */
+export declare const readLinkedFile: ReadPage;
+/**
+ * Whether an address is outside the page's folder: it has a scheme, or starts at the root or the page's own address.
+ *
+ * @param href - the address.
+ */
+export declare const isOutside: (href: string) => boolean;
+/**
+ * The file an address relative to a page names, and its fragment.
+ *
+ * @param file - the page's file.
+ * @param href - the address.
+ */
+export declare const relativeTarget: (file: string, href: string) => {
+    readonly file: string;
+    readonly fragment: string | undefined;
+};
+/**
+ * The folder of the package a file belongs to: the nearest with a `package.json`, or the file's own without one.
+ *
+ * @param file - the file.
+ */
+export declare const packageFolderOf: (file: string) => string;
+/**
+ * Whether a page may show a file as an image: a file of its own package. A build copies an image into the catalogue
+ * whatever it is, so a path that climbs out of the package would publish a file a reviewer took for a picture's name.
+ *
+ * @param file - the page's file.
+ * @param image - the image's file.
+ */
+export declare const isOwnImage: (file: string, image: string) => boolean;
+/**
+ * Whether a link names another page by its file.
+ *
+ * @param href - the link's address.
+ */
+export declare const isPageLink: (href: string) => boolean;
+/**
+ * The slug of the page a link names; none when its file is not there.
+ *
+ * @param file - the linking page's file.
+ * @param href - the link's address.
+ * @param read - reads a linked page's text.
+ */
+export declare const linkedSlug: (file: string, href: string, read: ReadPage) => string | undefined;
+/**
+ * The address the shell fills for a link to another page, by its slug; none when the file is not there.
+ *
+ * @param file - the linking page's file.
+ * @param href - the link's address.
+ * @param read - reads a linked page's text.
+ */
+export declare const pageAddress: (file: string, href: string, read: ReadPage) => string | undefined;
+/**
+ * The address an image's file is written as, by its place in the page's images.
+ *
+ * @param place - its place.
+ */
+export declare const assetAddress: (place: number) => string;
+/**
+ * The version of the package a file belongs to, from its `package.json`; none without one.
+ *
+ * @param file - the file.
+ */
+export declare const packageVersionOf: (file: string) => string | undefined;