forgebook 0.1.7 → 0.2.0

package/dist/src/vite/docPageTokens.js

@@ -0,0 +1,186 @@
+import { fenceInfo, missingLine } from "./codeFence.js";
+import { isPageValue, isValueToken, LEXER } from "./docMarkdown.js";
+import { assetAddress, isOutside, isOwnImage, isPageLink, linkedSlug, pageAddress, relativeTarget } from "./docPageLinks.js";
+/**
+ * Where each character of a text made of lines sits in the file.
+ *
+ * @param lines - the lines the text joins.
+ */
+export const positionsOf = (lines) => {
+    const starts = [];
+    let total = 0;
+    for (const line of lines) {
+        starts.push(total);
+        total += line.text.length + 1;
+    }
+    return (offset) => {
+        let index = starts.findLastIndex((start) => start <= offset);
+        if (index === -1)
+            index = 0;
+        const line = lines[index];
+        return line === undefined
+            ? { line: 1, column: 1 }
+            : { line: line.line, column: line.column + offset - (starts[index] ?? 0) };
+    };
+};
+/** Notes a value token, and writes `version` in. */
+const readValue = (token, position, reading) => {
+    if (!isValueToken(token))
+        return;
+    if (!isPageValue(token.name)) {
+        reading.notes.push({
+            position,
+            message: `\`${token.raw}\` is not a value a page can show: title, version, components, stories, libraries or pages`
+        });
+        return;
+    }
+    if (token.name !== "version")
+        return;
+    const version = reading.version();
+    if (version === undefined)
+        reading.notes.push({
+            position,
+            message: "`{{version}}` has no version to show: its package.json has none"
+        });
+    token.text = version ?? "";
+};
+/** Checks and addresses a link or an image, in place. */
+const readAddress = (token, position, reading) => {
+    if (token.type !== "link" && token.type !== "image")
+        return;
+    const href = token["href"];
+    if (typeof href !== "string" || isOutside(href))
+        return;
+    const { file, read } = reading;
+    if (token.type === "image") {
+        const image = relativeTarget(file, href).file;
+        if (!isOwnImage(file, image)) {
+            reading.notes.push({ position, message: `its image "${href}" is not a file of its package` });
+            return;
+        }
+        reading.images.push(image);
+        token.href = assetAddress(reading.images.length - 1);
+        return;
+    }
+    if (!isPageLink(href))
+        return;
+    const slug = linkedSlug(file, href, read);
+    if (slug === undefined) {
+        reading.notes.push({ position, message: `it links to "${href}", which is not there` });
+        return;
+    }
+    reading.links.push(slug);
+    token.href = pageAddress(file, href, read) ?? href;
+};
+/** The start of a fence's line after its backticks, where its words start. */
+const fenceWordsStart = (raw) => /^ {0,3}(?:`{3,}|~{3,})\s*/.exec(raw)?.[0].length ?? 3;
+/**
+ * Reads a top-level code fence: a story, a table, or code with its whole line.
+ *
+ * @param token - the fence.
+ * @param position - where it starts.
+ * @param reading - the reading.
+ */
+const readFence = (token, position, reading) => {
+    const info = typeof token.lang === "string" ? token.lang.trim() : "";
+    const words = info === "" ? [] : info.split(/\s+/);
+    const [kind, id, ...rest] = words;
+    if (kind !== undefined && reading.pluginFences.includes(kind)) {
+        reading.fences.set(token, { kind: "plugin", fence: kind, argument: words.slice(1).join(" ") });
+        return;
+    }
+    if (kind === "story" || kind === "props") {
+        if (id === undefined) {
+            reading.notes.push({ position, message: `a \`${kind}\` block names no id` });
+            return;
+        }
+        if (rest.length > 0)
+            reading.notes.push({
+                position,
+                message: `a \`${kind}\` block takes only an id, not "${rest.join(" ")}"`
+            });
+        (kind === "story" ? reading.stories : reading.components).push(id);
+        reading.fences.set(token, { kind, id });
+        return;
+    }
+    const start = { line: position.line, column: position.column + fenceWordsStart(token.raw) };
+    const read = fenceInfo(info, start, reading.notes);
+    const missing = missingLine(token.text, read);
+    if (missing !== undefined)
+        reading.notes.push({
+            position: start,
+            message: `the code fence names line ${missing.line}, and its code has ${missing.count}`
+        });
+    reading.fences.set(token, { kind: "code", info: read });
+};
+/**
+ * Whether a token is a code block.
+ *
+ * @param token - the token.
+ */
+export const isCode = (token) => token.type === "code" && typeof token["text"] === "string";
+/**
+ * Whether a token is an ordered list.
+ *
+ * @param token - the token.
+ */
+export const isOrderedList = (token) => token?.type === "list" && token["ordered"] === true && Array.isArray(token["items"]);
+/** Whether a fence names a page's own block (`story <id>`, `props <id>`). */
+const isBlockFence = (token) => isCode(token) && typeof token.lang === "string" && /^(story|props)(\s|$)/.test(token.lang.trim());
+/**
+ * Reads tokens that sit in a page's own flow: each fence a block, every link, image and value checked inside them.
+ *
+ * @param tokens - the tokens.
+ * @param container - the text they were read from.
+ * @param base - where that text starts in the text the positions are counted in.
+ * @param at - the position of a character of that text.
+ * @param reading - the reading.
+ */
+export const readTokens = (tokens, container, base, at, reading) => {
+    let cursor = 0;
+    for (const token of tokens) {
+        const found = container.indexOf(token.raw, cursor);
+        const start = found === -1 ? cursor : found;
+        cursor = start + token.raw.length;
+        const offset = base + start;
+        if (isCode(token))
+            readFence(token, at(offset), reading);
+        let inner = 0;
+        void LEXER.walkTokens([token], (child) => {
+            if (child === token)
+                return;
+            const place = placeIn(token.raw, child.raw, inner);
+            if (place !== -1)
+                inner = place;
+            const position = at(offset + (place === -1 ? 0 : place));
+            if (isBlockFence(child))
+                reading.notes.push({
+                    position,
+                    message: `a \`${(child.lang ?? "").trim()}\` block inside a list or a quote is not drawn`
+                });
+            readAddress(child, position, reading);
+            readValue(child, position, reading);
+        });
+        readAddress(token, at(offset), reading);
+    }
+};
+/**
+ * Where a nested token's text sits in its top-level token's, from a place on: its first line alone when the whole is
+ * not there, since a list item's lines lose their indent before they are read; -1 when neither is.
+ */
+const placeIn = (text, raw, from) => {
+    const whole = text.indexOf(raw, from);
+    if (whole !== -1)
+        return whole;
+    const firstLine = raw.split("\n")[0]?.trim() ?? "";
+    return firstLine === "" ? -1 : text.indexOf(firstLine, from);
+};
+/**
+ * A run of Markdown lines' text and its tokens.
+ *
+ * @param lines - the lines.
+ */
+export const lexed = (lines) => {
+    const text = lines.map((line) => line.text).join("\n");
+    return { text, tokens: [...LEXER.lexer(text)] };
+};

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

@@ -0,0 +1,50 @@
+import type { DocPageIndex } from "@forgebook/story-format/source";
+import type { ForgebookPlugin } from "../plugin.ts";
+/** A page a pattern matches, with its key and its index. */
+export type IndexedDocPage = {
+    /** Its path relative to the declaring module (`./docs/theming.md`). */
+    readonly key: string;
+    /** Its absolute path. */
+    readonly file: string;
+    /** Its index. */
+    readonly index: DocPageIndex;
+};
+/**
+ * Every page a pattern matches, indexed.
+ *
+ * @param root - the declaring module's folder.
+ * @param pattern - the pattern.
+ * @param watch - adds a file whose edit renews the module that read it.
+ * @param fences - the fences the catalogue's plugins draw, which are not code; none by default.
+ */
+export declare const indexedDocPages: (root: string, pattern: string, watch: (file: string) => void, fences?: readonly string[]) => IndexedDocPage[];
+/**
+ * The code of the module for one pattern.
+ *
+ * @param root - the declaring module's folder.
+ * @param pattern - the pattern before `?forgebook-docs-pages`.
+ * @param watch - adds a file whose edit renews the module (each page: its index is in the module).
+ * @param isServing - whether a dev server runs, whose tools read a page's Markdown.
+ * @param plugins - the catalogue's plugins, whose fences a page may draw; none by default.
+ */
+export declare const docPagesModule: (root: string, pattern: string, watch: (file: string) => void, isServing: boolean, plugins?: readonly ForgebookPlugin[]) => string;
+/**
+ * The code of one page's module: what the shell draws, each image imported so Vite answers its address, and, on the dev
+ * server, the page's Markdown for tools.
+ *
+ * @param file - the page's file, absolute.
+ * @param watch - adds a file whose edit renews the module.
+ * @param isServing - whether a dev server runs.
+ * @param plugins - the catalogue's plugins, whose fences a page may draw.
+ */
+export declare const docPageModule: (file: string, watch: (file: string) => void, isServing: boolean, plugins?: readonly ForgebookPlugin[]) => string;
+/**
+ * The code of the written home's module: what the shell draws in place of the generated home, with its problems, and,
+ * on the dev server, its Markdown for tools.
+ *
+ * @param file - the home's file, absolute.
+ * @param watch - adds a file whose edit renews the module.
+ * @param isServing - whether a dev server runs.
+ * @param plugins - the catalogue's plugins, whose fences the home may draw; none by default.
+ */
+export declare const homeModule: (file: string, watch: (file: string) => void, isServing: boolean, plugins?: readonly ForgebookPlugin[]) => string;

package/dist/src/vite/docPagesModule.js

@@ -0,0 +1,118 @@
+/**
+ * The modules that answer a `?forgebook-docs-pages` import: every page a pattern matches as one module with each page's
+ * index, and the loader of the page itself, and each page's own module.
+ *
+ * @remarks
+ * Shaped as `?forgebook-files` is, and keyed the same way: the sidebar needs every page's title at once, and a page's
+ * rendered blocks only when it opens. The Markdown itself goes to tools on the dev server alone: a static build has no
+ * tools to ask, and it would ship every page twice.
+ *
+ * @module
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { codeLiteral } from "../codeLiteral.js";
+import { readLinkedFile } from "./docPageLinks.js";
+import { compiledDocPage, compiledHome, docPageIndex } from "./docPageMarkdown.js";
+import { pluginFences } from "./pluginConfig.js";
+import { PAGES_SEARCH_PREFIX, storyFileKeys, storyFilesGroupText } from "./storyFilesModule.js";
+import { DOCS_PAGE_QUERY } from "./textQueries.js";
+import { VITE_PATHS } from "./vitePaths.js";
+/** Reads a linked page, watching it: its title makes the link's address, so a new title renews the page that links. */
+const watchedRead = (watch) => (file) => {
+    const text = readLinkedFile(file);
+    if (text !== undefined)
+        watch(file);
+    return text;
+};
+/**
+ * Every page a pattern matches, indexed.
+ *
+ * @param root - the declaring module's folder.
+ * @param pattern - the pattern.
+ * @param watch - adds a file whose edit renews the module that read it.
+ * @param fences - the fences the catalogue's plugins draw, which are not code; none by default.
+ */
+export const indexedDocPages = (root, pattern, watch, fences = []) => {
+    return storyFileKeys(root, [pattern]).map((key) => {
+        const file = resolve(root, key);
+        watch(file);
+        return { key, file, index: docPageIndex(file, readFileSync(file, "utf8"), watchedRead(watch), fences) };
+    });
+};
+/** An object literal of a key per page, each value written by `value`. */
+const objectOf = (keys, value) => `{${keys.map((key) => `${codeLiteral(key)}: ${value(key)}`).join(",\n")}}`;
+/**
+ * The code of the module for one pattern.
+ *
+ * @param root - the declaring module's folder.
+ * @param pattern - the pattern before `?forgebook-docs-pages`.
+ * @param watch - adds a file whose edit renews the module (each page: its index is in the module).
+ * @param isServing - whether a dev server runs, whose tools read a page's Markdown.
+ * @param plugins - the catalogue's plugins, whose fences a page may draw; none by default.
+ */
+export const docPagesModule = (root, pattern, watch, isServing, plugins = []) => {
+    const pages = indexedDocPages(root, pattern, watch, pluginFences(plugins));
+    const keys = pages.map((page) => page.key);
+    const index = Object.fromEntries(pages.map((page) => [page.key, page.index]));
+    const page = (key) => codeLiteral(`${VITE_PATHS.resolve(root, key)}${DOCS_PAGE_QUERY}`);
+    const search = codeLiteral(`${PAGES_SEARCH_PREFIX}${storyFilesGroupText(root, pattern)}`);
+    return [
+        "export default {",
+        `index: ${codeLiteral(index)},`,
+        `pages: ${objectOf(keys, (key) => `() => import(${page(key)}).then((module) => module.default)`)},`,
+        `search: () => import(${search}).then((module) => module.default),`,
+        ...(isServing
+            ? [`text: ${objectOf(keys, (key) => `() => import(${page(key)}).then((module) => module.text)`)}`]
+            : []),
+        "};"
+    ].join("\n");
+};
+/**
+ * The code of one page's module: what the shell draws, each image imported so Vite answers its address, and, on the dev
+ * server, the page's Markdown for tools.
+ *
+ * @param file - the page's file, absolute.
+ * @param watch - adds a file whose edit renews the module.
+ * @param isServing - whether a dev server runs.
+ * @param plugins - the catalogue's plugins, whose fences a page may draw.
+ */
+export const docPageModule = (file, watch, isServing, plugins = []) => {
+    watch(file);
+    const { blocks, headings, images, text } = compiledDocPage(file, readFileSync(file, "utf8"), watchedRead(watch), pluginFences(plugins));
+    return [
+        ...imageImports(images),
+        `export default { blocks: ${codeLiteral(blocks)}, headings: ${codeLiteral(headings)}, assets: ${assetList(images)} };`,
+        ...(isServing ? [`export const text = ${codeLiteral(text)};`] : [])
+    ].join("\n");
+};
+/** The imports of a page's images, each answered with its address. */
+const imageImports = (images) => images.map((image, place) => `import asset${place} from ${codeLiteral(`${VITE_PATHS.normalize(image)}?url`)};`);
+/** The list of a page's images' addresses, as the module's code writes it. */
+const assetList = (images) => `[${images.map((_image, place) => `asset${place}`).join(", ")}]`;
+/**
+ * The code of the written home's module: what the shell draws in place of the generated home, with its problems, and,
+ * on the dev server, its Markdown for tools.
+ *
+ * @param file - the home's file, absolute.
+ * @param watch - adds a file whose edit renews the module.
+ * @param isServing - whether a dev server runs.
+ * @param plugins - the catalogue's plugins, whose fences the home may draw; none by default.
+ */
+export const homeModule = (file, watch, isServing, plugins = []) => {
+    watch(file);
+    const { title, description, blocks, stories, notes, images, text } = compiledHome(file, readFileSync(file, "utf8"), watchedRead(watch), pluginFences(plugins));
+    const document = {
+        ...(title === undefined ? {} : { title }),
+        ...(description === undefined ? {} : { description }),
+        blocks,
+        stories,
+        // what the author got wrong is the dev server's to show: a published home keeps its readers out of it
+        notes: isServing ? notes : []
+    };
+    return [
+        ...imageImports(images),
+        `export default { ...${codeLiteral(document)}, assets: ${assetList(images)} };`,
+        ...(isServing ? [`export const text = ${codeLiteral(text)};`] : [])
+    ].join("\n");
+};

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

@@ -0,0 +1,38 @@
+import type { StoryTree } from "../storyTree.ts";
+import type { PagesDocument } from "./agent.types.ts";
+import type { CataloguePages } from "./agentApi.ts";
+import { type AgentAnswer, type RouteContext } from "./agentRoutes.ts";
+import type { HomeIndex } from "./docPageMarkdown.ts";
+/** The id `forgebook page` takes for the catalogue's written home. */
+export declare const HOME_PAGE_ID = "home";
+/** The written home read: its file from the configuration's folder, its index and its Markdown. */
+type ReadHome = {
+    readonly file: string;
+    readonly index: HomeIndex;
+    readonly text: string;
+};
+/**
+ * The docs pages a catalogue has.
+ *
+ * @param title - the catalogue's name.
+ * @param tree - its tree.
+ * @param pages - where it is served, for the links.
+ * @param view - the view the links open in; empty for the default view.
+ * @param home - the written home read; none for the generated one.
+ */
+export declare const pagesDocument: (title: string, tree: StoryTree, pages: CataloguePages, view: string, home?: ReadHome) => PagesDocument;
+/**
+ * The docs pages.
+ *
+ * @param context - what the routes read.
+ */
+export declare const pagesAnswer: ({ config, tree, pages, view }: RouteContext) => Promise<AgentAnswer>;
+/**
+ * One docs page: a page that cannot be read gives its problem in the answer, never an error, as a story does.
+ *
+ * @param context - what the routes read.
+ */
+export declare const pageAnswer: ({ params, tree, loaded, pages, view, config }: Omit<RouteContext, "config"> & {
+    readonly config?: Pick<RouteContext["config"], "title" | "home" | "dir" | "plugins">;
+}) => Promise<AgentAnswer>;
+export {};

package/dist/src/vite/docPagesRoute.js

@@ -0,0 +1,154 @@
+/**
+ * The answers about docs pages: the list, and one page to read; the catalogue's written home is listed beside them and
+ * read as the page `home`.
+ *
+ * @module
+ */
+import { readFileSync } from "node:fs";
+import { relative } from "node:path";
+import { isDocPage } from "../docPages.js";
+import { findPage } from "../pageTree.js";
+import { sourcePages } from "../sourceFiles.js";
+import { docPageAddressOf } from "../viewState.js";
+import { settled } from "./agentRoutes.js";
+import { pluginFences } from "./pluginConfig.js";
+/** The id `forgebook page` takes for the catalogue's written home. */
+export const HOME_PAGE_ID = "home";
+/**
+ * The catalogue's written home read from the disk; none without one, or when it cannot be read. The Markdown reader
+ * loads with the first question about it: a dev server whose tools never ask starts without it.
+ *
+ * @param home - its absolute path.
+ * @param dir - the configuration's folder.
+ * @param fences - the fences the catalogue's plugins draw, which are not code.
+ */
+const readHome = async (home, dir, fences) => {
+    if (home === undefined)
+        return undefined;
+    let text;
+    try {
+        text = readFileSync(home, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const [{ homeIndex }, { frontMatterOf }, { readLinkedFile }] = await Promise.all([
+        import("./docPageMarkdown.js"),
+        import("./docMarkdown.js"),
+        import("./docPageLinks.js")
+    ]);
+    return {
+        file: relative(dir, home),
+        index: homeIndex(home, text, readLinkedFile, fences),
+        text: frontMatterOf(text).body.trim()
+    };
+};
+/** The written home as the documents give it. */
+const agentHome = (title, home, pages, view) => ({
+    id: HOME_PAGE_ID,
+    title: home.index.title ?? title,
+    source: "",
+    file: home.file,
+    description: home.index.description,
+    stories: home.index.stories,
+    components: home.index.components,
+    links: { address: view === "" ? pages.page : `${pages.page}?${view}` }
+});
+/**
+ * What is wrong with the written home: its own notes, and the libraries its pieces name that the catalogue lacks.
+ *
+ * @param home - the home read.
+ * @param tree - the catalogue's tree.
+ */
+const homeProblems = (home, tree) => {
+    const known = new Set(tree.sources.map((source) => source.id));
+    const missing = [...new Set(home.index.sources)].filter((source) => !known.has(source));
+    return [
+        ...home.index.notes.map((note) => `Home: ${home.file}: ${note}`),
+        ...missing.map((source) => `Home: ${home.file}: it names the library "${source}", which the catalogue does not have`)
+    ];
+};
+/** A page of the tree as the documents give it. */
+const agentPage = (source, page, pages, view) => ({
+    id: page.id,
+    title: page.title,
+    source: source.id,
+    file: page.file,
+    description: page.description,
+    stories: page.stories,
+    components: page.components,
+    links: { address: docPageAddressOf(pages.page, page.id, view) }
+});
+/**
+ * The docs pages a catalogue has.
+ *
+ * @param title - the catalogue's name.
+ * @param tree - its tree.
+ * @param pages - where it is served, for the links.
+ * @param view - the view the links open in; empty for the default view.
+ * @param home - the written home read; none for the generated one.
+ */
+export const pagesDocument = (title, tree, pages, view, home) => ({
+    schema: 1,
+    title,
+    pages: tree.sources.flatMap((source) => source.pages.map((page) => agentPage(source, page, pages, view))),
+    ...(home === undefined ? {} : { home: agentHome(title, home, pages, view) }),
+    problems: [...tree.problems, ...(home === undefined ? [] : homeProblems(home, tree))]
+});
+/**
+ * The docs pages.
+ *
+ * @param context - what the routes read.
+ */
+export const pagesAnswer = async ({ config, tree, pages, view }) => ({
+    status: 200,
+    body: pagesDocument(config.title, tree, pages, view, await readHome(config.home, config.dir, pluginFences(config.plugins)))
+});
+/**
+ * The written home, read as a page: its Markdown and its problems; a catalogue without one answers it has none.
+ *
+ * @param config - the configuration's name, home and folder.
+ * @param tree - the catalogue's tree.
+ * @param pages - where it is served, for the links.
+ * @param view - the view the links open in.
+ */
+const homeAnswer = async (config, tree, pages, view) => {
+    const home = await readHome(config.home, config.dir, pluginFences(config.plugins));
+    if (home === undefined)
+        return { status: 404, body: { error: "This catalogue has no written home: its home is generated" } };
+    const body = {
+        schema: 1,
+        page: agentHome(config.title, home, pages, view),
+        headings: [],
+        text: home.text,
+        problems: homeProblems(home, tree)
+    };
+    return { status: 200, body };
+};
+/**
+ * One docs page: a page that cannot be read gives its problem in the answer, never an error, as a story does.
+ *
+ * @param context - what the routes read.
+ */
+export const pageAnswer = async ({ params, tree, loaded, pages, view, config }) => {
+    const id = params.get("id") ?? "";
+    if (id === HOME_PAGE_ID && config !== undefined)
+        return await homeAnswer(config, tree, pages, view);
+    const location = findPage(tree, id);
+    const source = loaded.sources.find((each) => each.id === location?.source.id);
+    if (location === undefined || source === undefined)
+        return { status: 404, body: { error: `No page "${id}"` } };
+    const files = sourcePages(source);
+    const rendered = await settled(files.pages[location.page.file]);
+    const text = await settled(files.text[location.page.file]);
+    const failures = [rendered, text].flatMap((read) => ("error" in read ? [read.error] : []));
+    const page = "value" in rendered && isDocPage(rendered.value) ? rendered.value : undefined;
+    const body = {
+        schema: 1,
+        page: agentPage(location.source, location.page, pages, view),
+        headings: page?.headings ?? [],
+        text: "value" in text && typeof text.value === "string" ? text.value : "",
+        problems: failures.slice(0, 1).map((failure) => `The page failed to load: ${failure}`)
+    };
+    return { status: 200, body };
+};

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

@@ -0,0 +1,6 @@
+/**
+ * The paths a group of story files' docs can change with, read in one walk.
+ *
+ * @param storyFiles - the story files.
+ */
+export declare const docsDependencies: (storyFiles: readonly string[]) => string[];