@t09tanaka/stoneage 0.1.0

package/dist/optimize.d.ts

@@ -0,0 +1,15 @@
+export type CompressedFile = {
+    path: string;
+    originalBytes: number;
+    brotliBytes: number;
+    gzipBytes: number;
+};
+export type CompressionMetrics = {
+    filesCompressed: number;
+    originalBytes: number;
+    brotliBytes: number;
+    gzipBytes: number;
+    files: CompressedFile[];
+};
+export declare function measureCompressedPublicOutput(outDir: string): Promise<CompressionMetrics>;
+export declare function compressPublicOutput(outDir: string): Promise<CompressionMetrics>;

package/dist/optimize.js

@@ -0,0 +1,215 @@
+import { createHash } from "node:crypto";
+import { brotliCompress, constants, gzip } from "node:zlib";
+import { promisify } from "node:util";
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, relative, sep } from "node:path";
+const brotliCompressAsync = promisify(brotliCompress);
+const gzipAsync = promisify(gzip);
+const compressionMeasurementConcurrency = 64;
+const compressibleExtensions = new Set([
+    ".html",
+    ".css",
+    ".js",
+    ".xml",
+    ".json",
+    ".csv",
+    ".txt",
+    ".svg",
+]);
+export async function measureCompressedPublicOutput(outDir) {
+    const files = await collectCompressiblePublicFiles(outDir);
+    return measureFiles(outDir, files);
+}
+export async function compressPublicOutput(outDir) {
+    const files = await collectCompressiblePublicFiles(outDir);
+    const previousManifest = await readCompressionManifest(outDir);
+    const nextManifest = {
+        version: 1,
+        files: {},
+    };
+    const compressedFiles = await Promise.all(files.map((path) => compressOrReuseFile(outDir, path, previousManifest, nextManifest)));
+    await writeCompressionManifest(outDir, nextManifest);
+    return {
+        filesCompressed: compressedFiles.length,
+        originalBytes: sum(compressedFiles, (file) => file.originalBytes),
+        brotliBytes: sum(compressedFiles, (file) => file.brotliBytes),
+        gzipBytes: sum(compressedFiles, (file) => file.gzipBytes),
+        files: compressedFiles,
+    };
+}
+async function collectCompressiblePublicFiles(outDir) {
+    const files = [];
+    await walk(outDir, async (path) => {
+        const publicPath = relative(outDir, path);
+        if (isCompressiblePath(publicPath)) {
+            files.push(publicPath);
+        }
+    });
+    return files.sort();
+}
+async function walk(dir, onFile) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.name === ".stoneage") {
+            continue;
+        }
+        const path = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            await walk(path, onFile);
+            continue;
+        }
+        if (entry.isFile()) {
+            await onFile(path);
+        }
+    }
+}
+async function measureFiles(outDir, files) {
+    const compressedFiles = await mapConcurrent(files, compressionMeasurementConcurrency, async (path) => {
+        const source = await readFile(join(outDir, path));
+        const [brotli, gzipped] = await Promise.all([compressBrotli(source), gzipAsync(source)]);
+        return {
+            path,
+            originalBytes: source.length,
+            brotliBytes: brotli.length,
+            gzipBytes: gzipped.length,
+        };
+    });
+    return {
+        filesCompressed: compressedFiles.length,
+        originalBytes: sum(compressedFiles, (file) => file.originalBytes),
+        brotliBytes: sum(compressedFiles, (file) => file.brotliBytes),
+        gzipBytes: sum(compressedFiles, (file) => file.gzipBytes),
+        files: compressedFiles,
+    };
+}
+async function mapConcurrent(items, concurrency, worker) {
+    const limit = Math.max(1, Math.floor(concurrency));
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    async function runWorker() {
+        while (nextIndex < items.length) {
+            const index = nextIndex;
+            nextIndex += 1;
+            results[index] = await worker(items[index]);
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, () => runWorker()));
+    return results;
+}
+async function compressOrReuseFile(outDir, path, previousManifest, nextManifest) {
+    const source = await readFile(join(outDir, path));
+    const sourceHash = hashBuffer(source);
+    const previous = previousManifest.files[path];
+    if (previous?.sourceHash === sourceHash && previous.originalBytes === source.length) {
+        const cached = await readCachedCompressedFile(outDir, path, previous);
+        if (cached) {
+            nextManifest.files[path] = previous;
+            return cached;
+        }
+    }
+    const [brotli, gzipped] = await Promise.all([compressBrotli(source), gzipAsync(source)]);
+    await Promise.all([
+        writeBufferIfChanged(join(outDir, `${path}.br`), brotli),
+        writeBufferIfChanged(join(outDir, `${path}.gz`), gzipped),
+    ]);
+    const entry = {
+        sourceHash,
+        brotliHash: hashBuffer(brotli),
+        gzipHash: hashBuffer(gzipped),
+        originalBytes: source.length,
+        brotliBytes: brotli.length,
+        gzipBytes: gzipped.length,
+    };
+    nextManifest.files[path] = entry;
+    return {
+        path,
+        originalBytes: entry.originalBytes,
+        brotliBytes: entry.brotliBytes,
+        gzipBytes: entry.gzipBytes,
+    };
+}
+async function readCachedCompressedFile(outDir, path, entry) {
+    try {
+        const [brotli, gzipped] = await Promise.all([
+            readFile(join(outDir, `${path}.br`)),
+            readFile(join(outDir, `${path}.gz`)),
+        ]);
+        if (brotli.length !== entry.brotliBytes ||
+            gzipped.length !== entry.gzipBytes ||
+            hashBuffer(brotli) !== entry.brotliHash ||
+            hashBuffer(gzipped) !== entry.gzipHash) {
+            return undefined;
+        }
+        return {
+            path,
+            originalBytes: entry.originalBytes,
+            brotliBytes: entry.brotliBytes,
+            gzipBytes: entry.gzipBytes,
+        };
+    }
+    catch (error) {
+        if (isMissingPath(error)) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+function compressBrotli(source) {
+    return brotliCompressAsync(source, {
+        params: {
+            [constants.BROTLI_PARAM_QUALITY]: 11,
+        },
+    });
+}
+function isCompressiblePath(path) {
+    if (path.split(sep).includes(".stoneage")) {
+        return false;
+    }
+    return [...compressibleExtensions].some((extension) => path.endsWith(extension));
+}
+function sum(items, valueOf) {
+    return items.reduce((total, item) => total + valueOf(item), 0);
+}
+async function writeBufferIfChanged(path, contents) {
+    try {
+        const current = await readFile(path);
+        if (current.equals(contents)) {
+            return;
+        }
+    }
+    catch (error) {
+        if (!isMissingPath(error)) {
+            throw error;
+        }
+    }
+    await writeFile(path, contents);
+}
+async function readCompressionManifest(outDir) {
+    try {
+        const parsed = JSON.parse(await readFile(compressionManifestPath(outDir), "utf8"));
+        if (parsed.version === 1 && parsed.files && typeof parsed.files === "object") {
+            return parsed;
+        }
+    }
+    catch {
+        // Missing or invalid compression metadata just means every file is recompressed.
+    }
+    return {
+        version: 1,
+        files: {},
+    };
+}
+async function writeCompressionManifest(outDir, manifest) {
+    const path = compressionManifestPath(outDir);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(manifest)}\n`);
+}
+function compressionManifestPath(outDir) {
+    return join(outDir, ".stoneage/compression-manifest.json");
+}
+function hashBuffer(value) {
+    return createHash("sha256").update(value).digest("base64url");
+}
+function isMissingPath(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}

package/dist/pagination.d.ts

@@ -0,0 +1,26 @@
+export type PaginationOptions = {
+    pageSize: number;
+};
+export type PaginatedPage<T> = {
+    items: T[];
+    page: number;
+    pageSize: number;
+    totalItems: number;
+    totalPages: number;
+};
+export type PaginationLinkOptions = PaginationOptions & {
+    pathForPage: (page: number) => string;
+};
+export type PaginationLinkPage = {
+    page: number;
+    path: string;
+    current: boolean;
+};
+export type PaginationLinks = {
+    previous?: string;
+    next?: string;
+    pages: PaginationLinkPage[];
+};
+export declare function paginate<T>(items: T[], options: PaginationOptions): PaginatedPage<T>[];
+export declare function pageForItemIndex(index: number, options: PaginationOptions): number;
+export declare function paginationLinks(page: number, totalItems: number, options: PaginationLinkOptions): PaginationLinks;

package/dist/pagination.js

@@ -0,0 +1,62 @@
+export function paginate(items, options) {
+    assertPageSize(options.pageSize);
+    const totalItems = items.length;
+    const totalPages = totalPagesForTotalItems(totalItems, options);
+    return Array.from({ length: totalPages }, (_, index) => {
+        const page = index + 1;
+        const start = index * options.pageSize;
+        return {
+            items: items.slice(start, start + options.pageSize),
+            page,
+            pageSize: options.pageSize,
+            totalItems,
+            totalPages,
+        };
+    });
+}
+export function pageForItemIndex(index, options) {
+    assertPageSize(options.pageSize);
+    if (!Number.isInteger(index) || index < 0) {
+        throw new Error("index must be a non-negative integer");
+    }
+    return Math.floor(index / options.pageSize) + 1;
+}
+export function paginationLinks(page, totalItems, options) {
+    assertPage(page);
+    assertTotalItems(totalItems);
+    const totalPages = totalPagesForTotalItems(totalItems, options);
+    if (page > totalPages) {
+        throw new Error("page must be between 1 and total pages");
+    }
+    return {
+        ...(page > 1 ? { previous: options.pathForPage(page - 1) } : {}),
+        ...(page < totalPages ? { next: options.pathForPage(page + 1) } : {}),
+        pages: Array.from({ length: totalPages }, (_, index) => {
+            const linkedPage = index + 1;
+            return {
+                page: linkedPage,
+                path: options.pathForPage(linkedPage),
+                current: linkedPage === page,
+            };
+        }),
+    };
+}
+function assertPageSize(pageSize) {
+    if (!Number.isInteger(pageSize) || pageSize <= 0) {
+        throw new Error("pageSize must be a positive integer");
+    }
+}
+function assertPage(page) {
+    if (!Number.isInteger(page) || page <= 0) {
+        throw new Error("page must be a positive integer");
+    }
+}
+function assertTotalItems(totalItems) {
+    if (!Number.isInteger(totalItems) || totalItems < 0) {
+        throw new Error("totalItems must be a non-negative integer");
+    }
+}
+function totalPagesForTotalItems(totalItems, options) {
+    assertPageSize(options.pageSize);
+    return Math.max(1, Math.ceil(totalItems / options.pageSize));
+}

package/dist/paths.d.ts

@@ -0,0 +1 @@
+export declare function publicAssetOutputPath(publicPath: string): string;

package/dist/paths.js

@@ -0,0 +1,10 @@
+import { posix } from "node:path";
+export function publicAssetOutputPath(publicPath) {
+    const [path] = publicPath.split(/[?#]/, 1);
+    const segments = (path ?? "").split("/");
+    const normalized = posix.normalize(`/${path ?? ""}`).replace(/^\/+/, "");
+    if (!path || path.endsWith("/") || segments.includes("..") || normalized === "") {
+        throw new Error(`Public asset path must not traverse outside the output directory: ${publicPath}`);
+    }
+    return normalized;
+}

package/dist/search.d.ts

@@ -0,0 +1,32 @@
+import type { ArtifactFamily, Dependency } from "./core.js";
+export type SearchIndexValue = string | number | boolean | null | undefined;
+export type SearchIndexDocument = {
+    id: string;
+    title: string;
+    url: string;
+    text?: string;
+    tags?: string[];
+    metadata?: Record<string, string | number | boolean | null>;
+};
+export type SearchIndexDocumentInput = Omit<SearchIndexDocument, "tags" | "metadata"> & {
+    tags?: readonly string[];
+    metadata?: Record<string, SearchIndexValue>;
+};
+export type SearchIndex = {
+    version: 1;
+    documents: SearchIndexDocument[];
+};
+export type BuildSearchIndexOptions = {
+    sort?: boolean;
+};
+export type SearchIndexArtifactOptions<RecordItem> = BuildSearchIndexOptions & {
+    name?: string;
+    path?: string;
+    dependencyKey?: string;
+    dependencies?: Dependency[] | ((index: SearchIndex) => Dependency[]);
+    records: readonly RecordItem[];
+    document: (record: RecordItem, index: number) => SearchIndexDocumentInput;
+    pretty?: boolean;
+};
+export declare function buildSearchIndex<RecordItem>(records: readonly RecordItem[], document: (record: RecordItem, index: number) => SearchIndexDocumentInput, options?: BuildSearchIndexOptions): SearchIndex;
+export declare function defineSearchIndexArtifact<RecordItem>(options: SearchIndexArtifactOptions<RecordItem>): ArtifactFamily;

package/dist/search.js

@@ -0,0 +1,55 @@
+import { renderJsonArtifact } from "./data.js";
+export function buildSearchIndex(records, document, options = {}) {
+    const documents = records.map((record, index) => normalizeSearchDocument(document(record, index)));
+    return {
+        version: 1,
+        documents: options.sort === false ? documents : documents.sort(compareSearchDocuments),
+    };
+}
+export function defineSearchIndexArtifact(options) {
+    return {
+        name: options.name ?? "searchIndex",
+        pattern: options.path ?? "/search-index.json",
+        entries: () => {
+            const index = buildSearchIndex(options.records, options.document, {
+                sort: options.sort,
+            });
+            const extraDependencies = typeof options.dependencies === "function"
+                ? options.dependencies(index)
+                : (options.dependencies ?? []);
+            return [
+                {
+                    params: {},
+                    dependencies: [
+                        {
+                            key: options.dependencyKey ?? "search:index",
+                            value: index,
+                        },
+                        ...extraDependencies,
+                    ],
+                    render: () => renderJsonArtifact(index, { pretty: options.pretty }),
+                },
+            ];
+        },
+    };
+}
+function normalizeSearchDocument(document) {
+    return {
+        id: document.id,
+        title: document.title,
+        url: document.url,
+        ...(document.text ? { text: document.text } : {}),
+        ...(document.tags && document.tags.length > 0
+            ? { tags: [...new Set(document.tags)].filter(Boolean).sort() }
+            : {}),
+        ...(document.metadata ? { metadata: normalizeSearchMetadata(document.metadata) } : {}),
+    };
+}
+function normalizeSearchMetadata(metadata) {
+    return Object.fromEntries(Object.entries(metadata)
+        .filter(([, value]) => value !== undefined)
+        .sort(([left], [right]) => left.localeCompare(right)));
+}
+function compareSearchDocuments(left, right) {
+    return left.url.localeCompare(right.url) || left.id.localeCompare(right.id);
+}

package/dist/testing.d.ts

@@ -0,0 +1,66 @@
+import { type HtmlNode } from "./html.js";
+export { renderToString } from "./html.js";
+export type { HtmlNode } from "./html.js";
+/**
+ * The result of rendering a component for assertions. Wraps the rendered HTML
+ * string with a few lightweight, dependency-free query helpers so component
+ * tests do not have to hand-roll string matching or pull in a DOM.
+ */
+export type RenderResult = {
+    /** The fully rendered HTML string. */
+    readonly html: string;
+    /**
+     * The visible text content, with all tags stripped and HTML entities for
+     * the characters StoneAge escapes (`&`, `<`, `>`, `"`) decoded back to their
+     * literal form. Whitespace between tags is collapsed to single spaces.
+     */
+    text(): string;
+    /**
+     * Whether the rendered HTML contains the given substring verbatim. The
+     * substring is matched against the raw (escaped) markup, so pass escaped
+     * entities when checking for literal `<`, `>` or `&` in text content.
+     */
+    contains(substring: string): boolean;
+    /**
+     * Reads the value of an attribute from the first element matching `tag`.
+     * `tag` is matched case-insensitively. Returns the decoded attribute value,
+     * `true` for valueless boolean attributes, or `undefined` when no matching
+     * element carries the attribute.
+     */
+    attr(tag: string, name: string): string | true | undefined;
+};
+export type StoneAgeVitestConfig = {
+    test?: Record<string, unknown>;
+    esbuild?: Record<string, unknown>;
+    [key: string]: unknown;
+};
+/**
+ * Renders a node to HTML and returns the string together with lightweight
+ * query helpers. This is intentionally a thin wrapper rather than a DOM
+ * implementation: it uses simple string and regular-expression matching, which
+ * is enough to assert on the static HTML StoneAge components produce.
+ */
+export declare function render(node: HtmlNode): RenderResult;
+/**
+ * A framework-agnostic assertion helper. It throws a plain `Error` (which every
+ * test runner reports as a failure) when an expectation fails, so it can be used
+ * from `node:test`, vitest, or any other runner without a dependency on one.
+ */
+export declare function expectMarkup(node: HtmlNode): MarkupAssertions;
+/**
+ * Assertions returned by {@link expectMarkup}. Each method throws on failure.
+ */
+export type MarkupAssertions = {
+    /** Asserts the rendered HTML exactly equals `expected`. */
+    toBe(expected: string): void;
+    /** Asserts the rendered HTML contains `substring` verbatim. */
+    toContain(substring: string): void;
+    /** Asserts the decoded visible text exactly equals `expected`. */
+    toHaveText(expected: string): void;
+};
+/**
+ * Returns a Vitest config preset for StoneAge component tests. It keeps Vitest
+ * in the consuming app's dev dependencies by returning a plain config object
+ * instead of importing `vitest/config`.
+ */
+export declare function stoneAgeVitestConfig(config?: StoneAgeVitestConfig): StoneAgeVitestConfig;

package/dist/testing.js

@@ -0,0 +1,97 @@
+import { renderToString } from "./html.js";
+export { renderToString } from "./html.js";
+const escapedEntities = [
+    [/"/g, '"'],
+    [/&lt;/g, "<"],
+    [/&gt;/g, ">"],
+    [/&amp;/g, "&"],
+];
+function decodeEntities(value) {
+    let output = value;
+    for (const [pattern, replacement] of escapedEntities) {
+        output = output.replace(pattern, replacement);
+    }
+    return output;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Renders a node to HTML and returns the string together with lightweight
+ * query helpers. This is intentionally a thin wrapper rather than a DOM
+ * implementation: it uses simple string and regular-expression matching, which
+ * is enough to assert on the static HTML StoneAge components produce.
+ */
+export function render(node) {
+    const html = renderToString(node);
+    return {
+        html,
+        text() {
+            return decodeEntities(html.replace(/<[^>]*>/g, " "))
+                .replace(/\s+/g, " ")
+                .trim();
+        },
+        contains(substring) {
+            return html.includes(substring);
+        },
+        attr(tag, name) {
+            const tagPattern = new RegExp(`<${escapeRegExp(tag)}(\\s[^>]*?)?\\s*/?>`, "i");
+            const tagMatch = tagPattern.exec(html);
+            if (tagMatch === null) {
+                return undefined;
+            }
+            const attributes = tagMatch[1] ?? "";
+            const valued = new RegExp(`(?:^|\\s)${escapeRegExp(name)}="([^"]*)"`).exec(attributes);
+            if (valued !== null) {
+                return decodeEntities(valued[1]);
+            }
+            const boolean = new RegExp(`(?:^|\\s)${escapeRegExp(name)}(?=\\s|$)`).exec(attributes);
+            return boolean !== null ? true : undefined;
+        },
+    };
+}
+/**
+ * A framework-agnostic assertion helper. It throws a plain `Error` (which every
+ * test runner reports as a failure) when an expectation fails, so it can be used
+ * from `node:test`, vitest, or any other runner without a dependency on one.
+ */
+export function expectMarkup(node) {
+    const { html, text, contains } = render(node);
+    return {
+        toBe(expected) {
+            if (html !== expected) {
+                throw new Error(`Expected markup to equal:\n${expected}\nReceived:\n${html}`);
+            }
+        },
+        toContain(substring) {
+            if (!contains(substring)) {
+                throw new Error(`Expected markup to contain ${JSON.stringify(substring)}.\nReceived:\n${html}`);
+            }
+        },
+        toHaveText(expected) {
+            const actual = text();
+            if (actual !== expected) {
+                throw new Error(`Expected text to equal ${JSON.stringify(expected)} but received ${JSON.stringify(actual)}.`);
+            }
+        },
+    };
+}
+/**
+ * Returns a Vitest config preset for StoneAge component tests. It keeps Vitest
+ * in the consuming app's dev dependencies by returning a plain config object
+ * instead of importing `vitest/config`.
+ */
+export function stoneAgeVitestConfig(config = {}) {
+    return {
+        ...config,
+        test: {
+            environment: "node",
+            ...(config.test ?? {}),
+        },
+        esbuild: {
+            jsxFactory: "html",
+            jsxFragment: "Fragment",
+            ...(config.esbuild ?? {}),
+        },
+    };
+}

package/dist/validate.d.ts

@@ -0,0 +1,2 @@
+export { validateOutput } from "./cli.js";
+export type { ValidationOutputOptions, ValidationSummary } from "./cli.js";

package/dist/validate.js

@@ -0,0 +1 @@
+export { validateOutput } from "./cli.js";

package/jsx-loader.mjs

@@ -0,0 +1,52 @@
+// StoneAge JSX loader: a Node module-customization "load" hook that compiles
+// .tsx/.jsx sources with esbuild using a FORCED html() JSX factory
+// (jsxFactory="html", jsxFragment="Fragment").
+//
+// This is what makes StoneAge TSX zero-config: the JSX factory is pinned at the
+// esbuild transform level, so it cannot be overridden by the consumer's own
+// tsconfig.json (e.g. jsx:"react-jsx", which otherwise causes
+// "React is not defined" / "Cannot find module react/jsx-runtime").
+//
+// It is layered ON TOP of tsx's loader (see jsx-register.mjs): tsx handles
+// module resolution (including NodeNext ".js" -> ".ts") and ESM/CJS interop and
+// compiles the remaining .ts sources, while this hook owns the JSX transform.
+import { fileURLToPath } from "node:url";
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+// Resolve esbuild from StoneAge's own dependency tree.
+const esbuild = require("esbuild");
+
+const JSX_EXTENSION = /\.(tsx|jsx)$/;
+const NODE_TARGET = `node${process.versions.node.split(".")[0]}`;
+
+export async function load(url, context, nextLoad) {
+  const pathname = url.startsWith("file:") ? new URL(url).pathname : "";
+  // Only transform the consumer's own .tsx/.jsx sources. Third-party packages
+  // under node_modules ship their own (often React) JSX and must not be
+  // recompiled with the html() factory.
+  if (
+    pathname &&
+    JSX_EXTENSION.test(pathname) &&
+    !pathname.includes("/node_modules/")
+  ) {
+    const path = fileURLToPath(url);
+    const source = await readFile(path, "utf8");
+    const { code, warnings } = await esbuild.transform(source, {
+      loader: "tsx",
+      jsx: "transform",
+      jsxFactory: "html",
+      jsxFragment: "Fragment",
+      format: "esm",
+      target: NODE_TARGET,
+      sourcefile: path,
+      sourcemap: "inline",
+    });
+    for (const warning of warnings) {
+      console.warn(`[stoneage] ${warning.text}`);
+    }
+    return { format: "module", source: code, shortCircuit: true };
+  }
+  return nextLoad(url, context);
+}

package/jsx-register.mjs

@@ -0,0 +1,7 @@
+// Registers the StoneAge JSX loader (jsx-loader.mjs) as a Node module
+// customization hook. Imported via `node --import` by `stoneage build` and
+// `stoneage test` so .tsx/.jsx sources compile with the html() JSX factory
+// forced, independent of the consumer's tsconfig.
+import { register } from "node:module";
+
+register(new URL("./jsx-loader.mjs", import.meta.url));