@staticforge/build 0.0.0-stage → 0.1.0

package/dist/build.js

@@ -0,0 +1,692 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { linkSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, posix } from 'node:path';
+import { h } from 'hastscript';
+import { toHtml } from 'hast-util-to-html';
+import { writeSearchIndex } from '@staticforge/assets';
+import { createReport, prepareSource } from '@staticforge/content';
+import { countBySeverity, createWorkerPool, mapInPool, poolSize, sortDiagnostics, } from '@staticforge/core';
+import { createRenderer, loadTheme, themeAssetUrl, } from '@staticforge/render';
+import { hashOf, memoized, stableJson } from './cache.js';
+import { isCode, processCode } from './code-assets.js';
+import { loadData } from './data.js';
+import { absolutizeHtml, atomFeed, FEED_ITEMS, robotsTxt, rssFeed, sitemapXml } from './feeds.js';
+import { finishFragment, finishTree } from './html.js';
+import { optimizeImages } from './images.js';
+import { navEntries } from './nav.js';
+import { PAGE_EXTENSIONS, ProjectDirs, listFiles, resolveOutDir, resolveScratchDir, } from './project.js';
+import { routeFor } from './routes.js';
+import { collectionsOf, listRoute, slugify, summarize, tagRoute, tagsOf, } from './site.js';
+import { MIN_PAGES_FOR_WORKERS, PARSE_TASK, RENDER_TASK, assetUrlFor, outputExists, parsePages, renderPages, } from './tasks.js';
+export const MANIFEST_PATH = '.sforge/build-manifest.json';
+/** Encoded image variants, kept between builds. */
+export const CACHE_DIR = '.sforge/cache';
+const ucfirst = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+export async function buildSite(options) {
+    if (options.pool !== undefined)
+        return build(options, options.pool);
+    // Workers start on first use, so a small site never pays for them.
+    const size = poolSize(options.config.build.workers);
+    const pool = size > 0 ? createWorkerPool(size) : undefined;
+    try {
+        return await build(options, pool);
+    }
+    finally {
+        await pool?.close();
+    }
+}
+async function build(options, pool) {
+    const started = performance.now();
+    const { rootDir, config, cache } = options;
+    const logger = options.logger;
+    cache?.begin();
+    const baseUrl = options.baseUrl ?? config.site.baseUrl;
+    const includeDrafts = options.drafts ?? config.build.drafts;
+    const minify = options.minify ?? config.build.minify;
+    const fingerprint = options.fingerprint ?? true;
+    const urlOptions = config.build;
+    const outDir = options.scratchDir !== undefined
+        ? resolveScratchDir(options.scratchDir)
+        : resolveOutDir(rootDir, options.outDir ?? config.build.outDir);
+    const diagnostics = [];
+    // Phase durations, logged at debug level (`--verbose`).
+    let phaseStart = started;
+    const phase = (name) => {
+        const now = performance.now();
+        logger?.debug(`build: ${name} ${Math.round(now - phaseStart)}ms`);
+        phaseStart = now;
+    };
+    const theme = loadTheme(config.theme, rootDir);
+    // 1. Claim every output path, reporting collisions.
+    const outputs = new Map();
+    const claim = (output, source) => {
+        const owner = outputs.get(output);
+        if (owner !== undefined) {
+            diagnostics.push({
+                ruleId: 'output-conflict',
+                severity: 'error',
+                message: `Both ${owner} and ${source} would be written to ${output}`,
+                file: source,
+            });
+            return false;
+        }
+        outputs.set(output, source);
+        return true;
+    };
+    const pages = [];
+    const copies = [];
+    const skippedDrafts = [];
+    const contentDir = join(rootDir, ProjectDirs.content);
+    for (const file of listFiles(contentDir)) {
+        const projectPath = `${ProjectDirs.content}/${file}`;
+        const ext = posix.extname(file).toLowerCase();
+        if (!PAGE_EXTENSIONS.has(ext)) {
+            if (claim(file, projectPath))
+                copies.push({ source: join(contentDir, file), output: file });
+            continue;
+        }
+        const format = ext === '.md' || ext === '.markdown' ? 'markdown' : 'html';
+        const text = readFileSync(join(contentDir, file), 'utf8');
+        const sourceKey = cache && hashOf(projectPath, format, text);
+        let prepared = sourceKey === undefined ? undefined : cache?.prepared.get(sourceKey);
+        if (prepared === undefined) {
+            prepared = prepareSource(text, projectPath, format);
+            if (sourceKey !== undefined)
+                cache?.prepared.set(sourceKey, prepared);
+        }
+        if (prepared.meta.draft && !includeDrafts) {
+            skippedDrafts.push(projectPath);
+            continue;
+        }
+        const route = routeFor(file, prepared.meta.slug, urlOptions);
+        if (claim(route.output, projectPath))
+            pages.push({ prepared, route, sourceKey });
+    }
+    const codeInputs = [];
+    const copyTree = (dir, prefix, label, processed) => {
+        for (const file of listFiles(dir)) {
+            const output = prefix + file;
+            if (!claim(output, `${label}/${file}`))
+                continue;
+            if (processed && isCode(file)) {
+                codeInputs.push({ source: join(dir, file), output, label: `${label}/${file}` });
+            }
+            else {
+                copies.push({ source: join(dir, file), output });
+            }
+        }
+    };
+    copyTree(join(rootDir, ProjectDirs.assets), 'assets/', ProjectDirs.assets, true);
+    copyTree(theme.assetsDir, themeAssetUrl('').slice(1), `theme:${theme.manifest.name}`, true);
+    copyTree(join(rootDir, ProjectDirs.static), '', ProjectDirs.static, false);
+    const copyByOutput = new Map(copies.map((c) => [c.output, c]));
+    phase('discover');
+    // 2. Stylesheets and scripts: bundle, minify, fingerprint.
+    const code = await processCode(codeInputs, { minify, fingerprint });
+    phase('stylesheets and scripts');
+    diagnostics.push(...code.diagnostics);
+    for (const out of code.outputs) {
+        if (!outputs.has(out.output))
+            claim(out.output, 'assets');
+    }
+    const assetUrl = assetUrlFor(code.urls);
+    const renderer = createRenderer(theme, { rootDir, baseUrl, assetUrl });
+    const hasNotFoundPage = outputs.has('404.html');
+    if (!hasNotFoundPage && renderer.hasLayout('404'))
+        claim('404.html', 'theme 404 layout');
+    const fileExists = (urlPath) => outputExists(outputs, urlPath);
+    // Global styles and scripts: theme first, then the project's.
+    const styles = [...theme.manifest.styles.map(themeAssetUrl), ...config.styles].map(assetUrl);
+    const scripts = [...theme.manifest.scripts.map(themeAssetUrl), ...config.scripts].map(assetUrl);
+    for (const url of [...config.styles, ...config.scripts]) {
+        if (url.startsWith('/') && !url.startsWith('//') && !code.urls.has(url) && !fileExists(url)) {
+            diagnostics.push({
+                ruleId: 'asset-missing',
+                severity: 'error',
+                message: `Configured stylesheet or script ${url} is not in the built site`,
+                hint: 'Put the file under assets/ (served at /assets/) or static/ (served at the site root).',
+            });
+        }
+    }
+    // 3. Parse every page (in workers for large sites); links resolve against the
+    // full set of page URLs and outputs. Images are optimized here, page by page.
+    const pageUrls = new Map(pages.map((p) => [p.prepared.path, p.route.url]));
+    const parseContext = {
+        language: config.site.language,
+        pageUrls,
+        outputs: new Set(outputs.keys()),
+        optimizeImages: config.images.optimize,
+    };
+    const parseContextKey = cache && hashOf(stableJson(parseContext));
+    const parseResults = await memoized(pages, cache?.parsed, (page) => hashOf(parseContextKey ?? '', page.sourceKey ?? ''), (missing) => mapInPool(pool, PARSE_TASK, missing.map((p) => p.prepared), parseContext, parsePages, {
+        minItems: MIN_PAGES_FOR_WORKERS,
+    }), 
+    // Trees are changed later in the build, so only pages without one are kept.
+    (result) => result.parsed.tree === undefined);
+    const parsedPages = parseResults.results;
+    if (cache)
+        cache.stats.parsed = parseResults.computed;
+    const imageOutputs = new Map();
+    const imageCache = new Map();
+    for (const [i, page] of pages.entries()) {
+        const { parsed, references } = parsedPages[i];
+        page.parsed = parsed;
+        diagnostics.push(...references, ...parsed.diagnostics);
+        const report = createReport(page.prepared.path, diagnostics);
+        if (config.images.optimize && parsed.kind === 'fragment' && parsed.tree !== undefined) {
+            await optimizeImages(parsed.tree, {
+                ...config.images,
+                cacheDir: join(rootDir, CACHE_DIR, 'images'),
+                sourceOf: (urlPath) => {
+                    try {
+                        return copyByOutput.get(decodeURI(urlPath).slice(1))?.source;
+                    }
+                    catch {
+                        return undefined;
+                    }
+                },
+                emit: (output, file) => {
+                    if (!imageOutputs.has(output) && claim(output, 'images'))
+                        imageOutputs.set(output, file);
+                },
+                fail: (node, message) => report({
+                    ruleId: 'image-failed',
+                    severity: 'warning',
+                    message: `Image could not be optimized and is used as is: ${message}`,
+                }, node),
+            }, imageCache);
+        }
+        logger?.debug(`parsed ${page.prepared.path} → ${page.route.url}`);
+    }
+    phase('parse');
+    // 4. Site features: collections, tags, feeds.
+    const sitePages = pages.flatMap(({ prepared, route, parsed }) => parsed === undefined || parsed.kind === 'document'
+        ? []
+        : [{ source: prepared.path, url: route.url, title: parsed.title, meta: prepared.meta }]);
+    const hasTagPages = renderer.hasLayout('tag');
+    const tagUrl = (slug) => (hasTagPages ? tagRoute(slug, urlOptions).url : undefined);
+    const summaries = new Map(sitePages.map((p) => [p.source, summarize(p, baseUrl, tagUrl)]));
+    const { collections, problems } = collectionsOf(config.collections, sitePages);
+    for (const message of problems) {
+        diagnostics.push({ ruleId: 'collection-invalid', severity: 'error', message });
+    }
+    const memberOf = new Map();
+    for (const c of collections)
+        for (const p of c.pages)
+            if (!memberOf.has(p.source))
+                memberOf.set(p.source, c.name);
+    const tagged = new Map();
+    for (const page of sitePages) {
+        for (const name of page.meta.tags) {
+            const slug = slugify(name);
+            const entry = tagged.get(slug) ?? { name, pages: [] };
+            entry.pages.push(page);
+            tagged.set(slug, entry);
+        }
+    }
+    const tags = [...tagged]
+        .map(([slug, { name, pages: tagPages }]) => ({
+        name,
+        slug,
+        url: tagUrl(slug),
+        count: tagPages.length,
+    }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    const titleOf = (c) => sitePages.find((p) => p.source === c.index)?.title ?? ucfirst(c.name);
+    const feeds = [];
+    const feedJobs = [];
+    for (const c of collections) {
+        const base = c.dir === '' ? '' : `${c.dir}/`;
+        for (const kind of ['rss', 'atom']) {
+            if (!c.feed[kind])
+                continue;
+            const output = `${base}${kind === 'rss' ? 'feed.xml' : 'atom.xml'}`;
+            if (!claim(output, `collection ${c.name}`))
+                continue;
+            const url = `/${encodeURI(output)}`;
+            feeds.push({
+                type: kind === 'rss' ? 'application/rss+xml' : 'application/atom+xml',
+                title: `${config.site.title}: ${titleOf(c)} (${kind === 'rss' ? 'RSS' : 'Atom'})`,
+                url,
+            });
+            feedJobs.push({ output, url, kind, collection: c });
+        }
+    }
+    // 5. Render jobs.
+    const pageContext = (fields) => ({
+        description: undefined,
+        absoluteUrl: new URL(fields.url, baseUrl).href,
+        lang: config.site.language,
+        date: undefined,
+        updated: undefined,
+        tags: [],
+        sourcePath: undefined,
+        headings: [],
+        data: {},
+        ...fields,
+        tagLinks: tagsOf(fields.tags ?? [], tagUrl),
+    });
+    const jobs = [];
+    const documents = [];
+    const indexJobs = new Map();
+    for (const job of pages) {
+        const { prepared, route, parsed } = job;
+        if (parsed === undefined)
+            continue;
+        if (parsed.kind === 'document') {
+            documents.push(job);
+            continue;
+        }
+        const collection = memberOf.get(prepared.path);
+        const isIndexOf = collections.find((c) => c.index === prepared.path);
+        let layout = prepared.meta.layout ??
+            (route.output === '404.html' && renderer.hasLayout('404')
+                ? '404'
+                : collection !== undefined && renderer.hasLayout('post')
+                    ? 'post'
+                    : isIndexOf !== undefined && renderer.hasLayout('list')
+                        ? 'list'
+                        : theme.manifest.defaultLayout);
+        if (!renderer.hasLayout(layout)) {
+            diagnostics.push({
+                ruleId: 'layout-missing',
+                severity: 'error',
+                message: `Layout "${layout}" does not exist in theme "${theme.manifest.name}"`,
+                file: prepared.path,
+                line: 1,
+            });
+            layout = theme.manifest.defaultLayout;
+        }
+        const renderJob = {
+            route,
+            layout,
+            source: prepared.path,
+            content: parsed.html ?? toHtml(parsed.tree),
+            page: pageContext({
+                title: parsed.title,
+                description: prepared.meta.description,
+                url: route.url,
+                lang: parsed.lang,
+                date: prepared.meta.date,
+                updated: prepared.meta.updated,
+                tags: prepared.meta.tags,
+                layout,
+                sourcePath: prepared.path,
+                headings: parsed.headings,
+                data: prepared.meta,
+                collection,
+            }),
+        };
+        jobs.push(renderJob);
+        if (isIndexOf !== undefined)
+            indexJobs.set(isIndexOf.name, renderJob);
+    }
+    // Collection list pages: the index page is page 1, later pages are generated.
+    const hasList = renderer.hasLayout('list');
+    for (const c of collections) {
+        const count = Math.max(1, Math.ceil(c.pages.length / c.perPage));
+        const routes = Array.from({ length: count }, (_, i) => listRoute(c.dir, i + 1, urlOptions));
+        const title = titleOf(c);
+        for (let n = 1; n <= count; n++) {
+            const route = routes[n - 1];
+            const pagination = {
+                collection: c.name,
+                page: n,
+                pages: count,
+                total: c.pages.length,
+                items: c.pages
+                    .slice((n - 1) * c.perPage, n * c.perPage)
+                    .flatMap((p) => summaries.get(p.source) ?? []),
+                first: routes[0].url,
+                last: routes[count - 1].url,
+                prev: routes[n - 2]?.url,
+                next: routes[n]?.url,
+            };
+            const index = n === 1 ? indexJobs.get(c.name) : undefined;
+            if (index !== undefined) {
+                index.pagination = pagination;
+                continue;
+            }
+            // Without a list layout there are no generated list pages.
+            if (!hasList)
+                break;
+            if (n === 1 && outputs.has(route.output))
+                continue;
+            if (!claim(route.output, `collection ${c.name}`))
+                continue;
+            jobs.push({
+                route,
+                layout: 'list',
+                source: undefined,
+                content: '',
+                pagination,
+                page: pageContext({
+                    title: n === 1 ? title : `${title} (page ${n} of ${count})`,
+                    url: route.url,
+                    layout: 'list',
+                }),
+            });
+        }
+    }
+    if (hasTagPages) {
+        for (const tag of tags) {
+            const route = tagRoute(tag.slug, urlOptions);
+            if (!claim(route.output, `tag ${tag.name}`))
+                continue;
+            const items = (tagged.get(tag.slug)?.pages ?? [])
+                .flatMap((p) => summaries.get(p.source) ?? [])
+                .sort((a, b) => (b.date?.getTime() ?? -Infinity) - (a.date?.getTime() ?? -Infinity) ||
+                a.title.localeCompare(b.title));
+            jobs.push({
+                route,
+                layout: 'tag',
+                source: undefined,
+                content: '',
+                tag: { ...tag, items },
+                page: pageContext({ title: `Tagged “${tag.name}”`, url: route.url, layout: 'tag' }),
+            });
+        }
+    }
+    // The tag index: generated, or a content page at its URL (tags/index.md).
+    let tagsUrl;
+    const tagsIndex = tagRoute(undefined, urlOptions);
+    if (outputs.has(tagsIndex.output)) {
+        tagsUrl = tagsIndex.url;
+    }
+    else if (tags.length > 0 && renderer.hasLayout('tags') && claim(tagsIndex.output, 'tags')) {
+        tagsUrl = tagsIndex.url;
+        jobs.push({
+            route: tagsIndex,
+            layout: 'tags',
+            source: undefined,
+            content: '',
+            page: pageContext({ title: 'Tags', url: tagsIndex.url, layout: 'tags' }),
+        });
+    }
+    const searchRoute = routeFor('search.md', undefined, urlOptions);
+    let search;
+    if (config.search.enabled && renderer.hasLayout('search')) {
+        if (outputs.has(searchRoute.output) || claim(searchRoute.output, 'search')) {
+            search = { url: searchRoute.url };
+            if (outputs.get(searchRoute.output) === 'search') {
+                jobs.push({
+                    route: searchRoute,
+                    layout: 'search',
+                    source: undefined,
+                    content: '',
+                    page: pageContext({
+                        title: 'Search',
+                        url: searchRoute.url,
+                        layout: 'search',
+                        data: { sitemap: false },
+                    }),
+                });
+            }
+        }
+    }
+    if (!hasNotFoundPage && renderer.hasLayout('404')) {
+        jobs.push({
+            route: { url: '/404.html', output: '404.html' },
+            layout: '404',
+            source: undefined,
+            content: '',
+            page: pageContext({ title: 'Page not found', url: '/404.html', layout: '404' }),
+        });
+    }
+    phase('site features');
+    // 6. Render and write.
+    const nav = navEntries(pages.flatMap(({ prepared, route, parsed }) => parsed === undefined ? [] : [{ url: route.url, title: parsed.title, nav: prepared.meta.nav }]));
+    const titles = new Map([
+        ...sitePages.map((p) => [p.url, p.title]),
+        ...jobs.map((j) => [j.route.url, j.page.title]),
+    ]);
+    const data = loadData(rootDir, diagnostics);
+    const now = cache?.time ?? new Date();
+    const base = {
+        site: {
+            title: config.site.title,
+            description: config.site.description,
+            author: config.site.author,
+            language: config.site.language,
+            baseUrl,
+        },
+        theme: { styles, scripts },
+        data,
+        build: {
+            generator: options.generator ?? 'staticforge',
+            time: now.toISOString(),
+            year: now.getUTCFullYear(),
+        },
+        collections: Object.fromEntries(collections.map((c) => [c.name, c.pages.flatMap((p) => summaries.get(p.source) ?? [])])),
+        tags,
+        tagsUrl,
+        feeds,
+        search,
+    };
+    rmSync(outDir, { recursive: true, force: true });
+    const manifest = {};
+    const record = (output, contents, immutable = false) => {
+        manifest[output] = {
+            sha256: createHash('sha256').update(contents).digest('hex'),
+            size: Buffer.byteLength(contents),
+            cache: immutable ? 'immutable' : 'revalidate',
+        };
+    };
+    const write = (output, contents, immutable = false) => {
+        const path = join(outDir, output);
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, contents);
+        record(output, contents, immutable);
+    };
+    const finish = { assetUrl, minify };
+    const built = [];
+    const indexed = [];
+    const bodies = new Map();
+    // Render with the layouts and finish (in workers for large sites), then write in job order.
+    const shared = {
+        buildId: randomUUID(),
+        theme: config.theme,
+        rootDir,
+        baseUrl,
+        assetUrls: code.urls,
+        minify,
+        base,
+        nav,
+        titles,
+    };
+    const renderItems = jobs.map((job) => ({
+        layout: job.layout,
+        url: job.route.url,
+        page: job.page,
+        content: job.content,
+        ...(job.pagination && { pagination: job.pagination }),
+        ...(job.tag && { tag: job.tag }),
+    }));
+    // A page renders the same when its item, the shared context and the templates are the same.
+    const renderContextKey = cache && hashOf(stableJson({ ...shared, buildId: '' }), templatesKey(theme.dir, rootDir));
+    const renderedPages = await memoized(renderItems, cache?.rendered, (item) => hashOf(renderContextKey ?? '', stableJson(item)), async (missing) => (await mapInPool(pool, RENDER_TASK, missing, shared, renderPages, {
+        minItems: MIN_PAGES_FOR_WORKERS,
+    })).map((result) => ('html' in result ? result.html : result)), (result) => typeof result === 'string');
+    const rendered = renderedPages.results.map((result) => typeof result === 'string' ? { html: result } : result);
+    if (cache)
+        cache.stats.rendered = renderedPages.computed;
+    for (const [i, job] of jobs.entries()) {
+        const result = rendered[i];
+        if ('error' in result) {
+            diagnostics.push({
+                ruleId: 'render-failed',
+                severity: 'error',
+                message: result.error,
+                ...(job.source !== undefined && { file: job.source }),
+            });
+            continue;
+        }
+        const finished = result.html;
+        write(job.route.output, finished);
+        if (job.source !== undefined)
+            bodies.set(job.source, job.content);
+        indexed.push({ url: job.route.url, html: finished });
+        built.push({
+            source: job.source,
+            url: job.route.url,
+            output: job.route.output,
+            layout: job.layout,
+        });
+    }
+    for (const { prepared, route, parsed } of documents) {
+        if (parsed?.tree === undefined)
+            continue;
+        injectHead(parsed.tree, styles, scripts);
+        finishTree(parsed.tree, finish);
+        const html = toHtml(parsed.tree);
+        write(route.output, html);
+        indexed.push({ url: route.url, html });
+        built.push({ source: prepared.path, url: route.url, output: route.output, layout: 'document' });
+    }
+    phase('render');
+    // Feeds, sitemap and robots.txt.
+    for (const feed of feedJobs) {
+        const c = feed.collection;
+        const listUrl = listRoute(c.dir, 1, urlOptions).url;
+        const items = c.pages.slice(0, FEED_ITEMS).map((p) => {
+            const body = bodies.get(p.source);
+            return {
+                page: summaries.get(p.source),
+                html: body === undefined ? undefined : absolutizeHtml(finishFragment(body, finish), baseUrl),
+            };
+        });
+        const feedOptions = {
+            title: `${config.site.title}: ${titleOf(c)}`,
+            description: config.site.description,
+            language: config.site.language,
+            author: config.site.author,
+            link: new URL(listUrl, baseUrl).href,
+            self: new URL(feed.url, baseUrl).href,
+            items,
+            fallbackDate: now,
+            generator: base.build.generator,
+        };
+        write(feed.output, feed.kind === 'rss' ? rssFeed(feedOptions) : atomFeed(feedOptions));
+    }
+    const metaBySource = new Map(pages.map((p) => [p.prepared.path, p.prepared.meta]));
+    // Pages opt out with `sitemap: false`; the generated search page does too.
+    const unlisted = new Set(jobs.filter((j) => j.page.data.sitemap === false).map((j) => j.route.url));
+    const sitemapEntries = built
+        .filter((p) => p.output !== '404.html' && !unlisted.has(p.url))
+        .filter((p) => p.source === undefined || metaBySource.get(p.source)?.sitemap !== false)
+        .map((p) => {
+        const meta = p.source === undefined ? undefined : metaBySource.get(p.source);
+        return { url: new URL(p.url, baseUrl).href, lastmod: meta?.updated ?? meta?.date };
+    })
+        .sort((a, b) => a.url.localeCompare(b.url));
+    if (!outputs.has('sitemap.xml') && claim('sitemap.xml', 'sitemap')) {
+        write('sitemap.xml', sitemapXml(sitemapEntries));
+    }
+    if (!outputs.has('robots.txt') && claim('robots.txt', 'robots')) {
+        write('robots.txt', robotsTxt(new URL('/sitemap.xml', baseUrl).href));
+    }
+    // Copies the previous build already has (same source, size and time) are hard-linked.
+    const copyRecords = new Map();
+    const copyFile = (output, source, immutable) => {
+        if (cache === undefined) {
+            write(output, readFileSync(source), immutable);
+            return;
+        }
+        const { size, mtimeMs } = statSync(source);
+        const previous = cache.previous;
+        const before = previous?.copies.get(output);
+        if (previous !== undefined &&
+            before?.source === source &&
+            before.size === size &&
+            before.mtimeMs === mtimeMs) {
+            const path = join(outDir, output);
+            mkdirSync(dirname(path), { recursive: true });
+            try {
+                linkSync(join(previous.outDir, output), path);
+                manifest[output] = {
+                    sha256: before.sha256,
+                    size,
+                    cache: immutable ? 'immutable' : 'revalidate',
+                };
+                copyRecords.set(output, before);
+                cache.stats.linked++;
+                return;
+            }
+            catch {
+                // Gone or on another device: copy it.
+            }
+        }
+        write(output, readFileSync(source), immutable);
+        copyRecords.set(output, {
+            source,
+            size,
+            mtimeMs,
+            sha256: manifest[output].sha256,
+        });
+    };
+    for (const copy of copies)
+        copyFile(copy.output, copy.source, false);
+    for (const out of code.outputs)
+        write(out.output, out.contents, out.immutable);
+    for (const [output, file] of imageOutputs)
+        copyFile(output, file, true);
+    phase('feeds, sitemap and copies');
+    // Search index, over the finished pages.
+    if (config.search.enabled && options.deferSearch !== undefined) {
+        options.deferSearch(async () => void (await writeSearchIndex(indexed, outDir)));
+    }
+    else if (config.search.enabled) {
+        try {
+            for (const file of await writeSearchIndex(indexed, outDir)) {
+                record(file, readFileSync(join(outDir, file)));
+            }
+        }
+        catch (error) {
+            diagnostics.push({
+                ruleId: 'search-failed',
+                severity: 'error',
+                message: `Search index could not be built: ${error instanceof Error ? error.message : String(error)}`,
+            });
+        }
+    }
+    if (config.search.enabled && options.deferSearch === undefined)
+        phase('search index');
+    const sorted = sortDiagnostics(diagnostics);
+    const summary = countBySeverity(sorted);
+    write(MANIFEST_PATH, `${JSON.stringify({ version: 1, generator: base.build.generator, builtAt: base.build.time, baseUrl, files: manifest }, null, 2)}\n`);
+    cache?.commit({ outDir, copies: copyRecords });
+    return {
+        ok: summary.error === 0,
+        outDir,
+        pages: built.sort((a, b) => a.url.localeCompare(b.url)),
+        fileCount: Object.keys(manifest).length - 1,
+        drafts: { skipped: skippedDrafts },
+        diagnostics: sorted,
+        summary,
+        durationMs: Math.round(performance.now() - started),
+    };
+}
+/** Hash of the theme's and the project's template files. */
+function templatesKey(themeDir, rootDir) {
+    const parts = [];
+    for (const dir of [themeDir, join(rootDir, 'templates')]) {
+        for (const file of listFiles(dir)) {
+            if (file.endsWith('.njk') || file === 'theme.json') {
+                parts.push(dir, file, readFileSync(join(dir, file), 'utf8'));
+            }
+        }
+    }
+    return hashOf(...parts);
+}
+/** Add theme and site styles/scripts to a pass-through document's <head>. */
+function injectHead(tree, styles, scripts) {
+    const html = tree.children.find((n) => n.type === 'element' && n.tagName === 'html');
+    const head = html?.children.find((n) => n.type === 'element' && n.tagName === 'head');
+    if (head === undefined)
+        return;
+    // Insert after leading <meta> elements (charset, viewport) so author styles still win.
+    const firstNonMeta = head.children.findIndex((n) => !(n.type === 'element' && n.tagName === 'meta') && n.type !== 'text');
+    const at = firstNonMeta === -1 ? head.children.length : firstNonMeta;
+    head.children.splice(at, 0, ...styles.map((href) => h('link', { rel: 'stylesheet', href })), ...scripts.map((src) => h('script', { type: 'module', src })));
+}
+//# sourceMappingURL=build.js.map