@webstir-io/webstir-frontend 0.1.40 → 0.1.41

package/dist/builders/contentBuilder.js

@@ -1,10 +1,10 @@
 import path from 'node:path';
-import { glob } from 'glob';
 import { marked } from 'marked';
 import { load } from 'cheerio';
 import hljs from 'highlight.js/lib/common';
 import { FOLDERS, FILES, FILE_NAMES, EXTENSIONS } from '../core/constants.js';
 import { ensureDir, pathExists, readFile, readJson, remove, writeFile } from '../utils/fs.js';
+import { scanGlob } from '../utils/glob.js';
 import { shouldProcess } from '../utils/changedFile.js';
 import { getPageDirectories } from '../core/pages.js';
 import { readPageManifest, readSharedAssets } from '../assets/assetManifest.js';
@@ -20,7 +20,7 @@ export function createContentBuilder(context) {
         async publish() {
             await publishContentPages(context);
             await publishContentManifests(context);
-        }
+        },
     };
 }
 async function buildContentPages(context) {
@@ -29,13 +29,11 @@ async function buildContentPages(context) {
     if (!(await pathExists(contentRoot))) {
         return;
     }
-    if (!shouldProcess(context, [{ directory: contentRoot, extensions: ['.md'] }])) {
+    if (!isSidebarOverrideChange(context, contentRoot) &&
+        !shouldProcess(context, [{ directory: contentRoot, extensions: ['.md'] }])) {
         return;
     }
-    const files = await glob('**/*.md', {
-        cwd: contentRoot,
-        nodir: true
-    });
+    const files = await scanGlob('**/*.md', { cwd: contentRoot });
     if (files.length === 0) {
         return;
     }
@@ -46,9 +44,7 @@ async function buildContentPages(context) {
     const templateHtml = await readFile(appTemplatePath);
     validateAppTemplate(templateHtml, appTemplatePath);
     const buildPagesUrlPrefix = resolvePagesUrlPrefix(config.paths.build.frontend, config.paths.build.pages);
-    const navEntries = context.enable?.contentNav === true
-        ? await collectContentManifests(context)
-        : [];
+    const navEntries = context.enable?.contentNav === true ? await collectContentManifests(context) : [];
     await removeStaleContentOutputs(context, files, buildPagesUrlPrefix);
     for (const relative of files) {
         const sourcePath = path.join(contentRoot, relative);
@@ -57,7 +53,7 @@ async function buildContentPages(context) {
         const htmlBody = (await renderMarkdownDoc(content)).html;
         const segments = resolveDocsSegments(relative);
         const pagePath = path.join(...segments);
-        const href = '/' + segments.join('/') + '/';
+        const href = `/${segments.join('/')}/`;
         const pageTitle = resolveTitle(frontmatter, content, segments);
         const mergedHtml = mergeContentIntoTemplate(templateHtml, pageTitle, htmlBody, frontmatter.description, context.enable?.contentNav === true, buildPagesUrlPrefix, navEntries, href);
         const mergedWithOptIn = injectGlobalOptInScripts(mergedHtml, context.enable);
@@ -74,10 +70,7 @@ async function publishContentPages(context) {
     if (!(await pathExists(contentRoot))) {
         return;
     }
-    const files = await glob('**/*.md', {
-        cwd: contentRoot,
-        nodir: true
-    });
+    const files = await scanGlob('**/*.md', { cwd: contentRoot });
     if (files.length === 0) {
         return;
     }
@@ -91,9 +84,7 @@ async function publishContentPages(context) {
     const buildPagesUrlPrefix = resolvePagesUrlPrefix(config.paths.build.frontend, config.paths.build.pages);
     await removeStaleContentOutputsForRoot(config.paths.dist.content, files, pagesUrlPrefix);
     const shared = await readSharedAssets(config.paths.dist.frontend);
-    const navEntries = context.enable?.contentNav === true
-        ? await collectContentManifests(context)
-        : [];
+    const navEntries = context.enable?.contentNav === true ? await collectContentManifests(context) : [];
     const docsManifestRoot = path.join(config.paths.dist.pages, 'docs');
     const docsManifest = await readPageManifest(docsManifestRoot, 'docs');
     if (!docsManifest.css || !docsManifest.js) {
@@ -106,7 +97,7 @@ async function publishContentPages(context) {
         const { frontmatter, content } = extractFrontmatter(markdown);
         const segments = resolveDocsSegments(relative);
         const pagePath = path.join(...segments);
-        const href = '/' + segments.join('/') + '/';
+        const href = `/${segments.join('/')}/`;
         const pageTitle = resolveTitle(frontmatter, content, segments);
         const rendered = await renderMarkdownDoc(content);
         const htmlBody = rendered.html;
@@ -114,7 +105,7 @@ async function publishContentPages(context) {
         const mergedWithOptIn = injectGlobalOptInScripts(mergedHtml, context.enable);
         const rewritten = await rewriteContentForPublish(mergedWithOptIn, shared, docsManifest, {
             pagesUrlPrefix,
-            buildPagesUrlPrefix
+            buildPagesUrlPrefix,
         });
         const distDir = path.join(config.paths.dist.pages, pagePath);
         const distPath = path.join(distDir, FILES.indexHtml);
@@ -124,7 +115,7 @@ async function publishContentPages(context) {
             outputPath: distPath,
             html: rewritten,
             headingIds: rendered.headingIds,
-            sourcePath
+            sourcePath,
         });
     }
     validateRenderedContentPages(renderedPages);
@@ -145,10 +136,7 @@ async function removeStaleContentOutputsForRoot(docsRoot, contentFiles, pagesUrl
         const segments = resolveDocsSegments(relative);
         expected.add(path.join(...segments.slice(1)));
     }
-    const candidateIndexes = await glob('**/index.html', {
-        cwd: docsRoot,
-        nodir: true
-    });
+    const candidateIndexes = await scanGlob('**/index.html', { cwd: docsRoot });
     const docsPrefix = resolvePageAssetUrl(pagesUrlPrefix, 'docs', '');
     const docsAssetToken = docsPrefix.endsWith('/') ? docsPrefix : `${docsPrefix}/`;
     for (const relativeIndex of candidateIndexes) {
@@ -163,8 +151,7 @@ async function removeStaleContentOutputsForRoot(docsRoot, contentFiles, pagesUrl
         const absoluteIndex = path.join(docsRoot, relativeIndex);
         const html = await readFile(absoluteIndex);
         // Only remove pages that were generated by the content pipeline (avoid deleting user-owned pages under /docs).
-        const looksLikeContentOutput = html.includes('class="docs-article"')
-            && html.includes(docsAssetToken);
+        const looksLikeContentOutput = html.includes('class="docs-article"') && html.includes(docsAssetToken);
         if (!looksLikeContentOutput) {
             continue;
         }
@@ -184,11 +171,12 @@ async function buildContentManifests(context) {
         }
         return;
     }
-    if (!shouldProcess(context, [
-        { directory: contentRoot, extensions: ['.md'] },
-        // `webstir enable search` updates package.json and should emit the index immediately.
-        { directory: config.paths.workspace, extensions: ['.json'] }
-    ])) {
+    if (!isSidebarOverrideChange(context, contentRoot) &&
+        !shouldProcess(context, [
+            { directory: contentRoot, extensions: ['.md'] },
+            // `webstir enable search` updates package.json and should emit the index immediately.
+            { directory: config.paths.workspace, extensions: ['.json'] },
+        ])) {
         return;
     }
     const navEntries = await collectContentManifests(context);
@@ -199,7 +187,7 @@ async function buildContentManifests(context) {
     if (context.enable?.search === true) {
         const [docEntries, pageEntries] = await Promise.all([
             collectContentSearchEntries(context),
-            collectPageSearchEntries(context)
+            collectPageSearchEntries(context),
         ]);
         const searchEntries = [...docEntries, ...pageEntries];
         if (searchEntries.length > 0) {
@@ -218,7 +206,7 @@ async function publishContentManifests(context) {
     if (context.enable?.search === true) {
         const [docEntries, pageEntries] = await Promise.all([
             hasContent ? collectContentSearchEntries(context) : Promise.resolve([]),
-            collectPageSearchEntries(context)
+            collectPageSearchEntries(context),
         ]);
         const searchEntries = [...docEntries, ...pageEntries];
         if (searchEntries.length > 0) {
@@ -230,10 +218,7 @@ async function collectContentManifests(context) {
     const { config } = context;
     const contentRoot = config.paths.src.content;
     const overrides = await loadSidebarOverrides(contentRoot);
-    const files = await glob('**/*.md', {
-        cwd: contentRoot,
-        nodir: true
-    });
+    const files = await scanGlob('**/*.md', { cwd: contentRoot });
     if (files.length === 0) {
         return [];
     }
@@ -244,17 +229,15 @@ async function collectContentManifests(context) {
         const { frontmatter, content } = extractFrontmatter(markdown);
         const segments = resolveDocsSegments(relative);
         const parsed = path.parse(relative);
-        const section = parsed.dir && parsed.dir.trim().length > 0
-            ? parsed.dir.split(path.sep)[0]
-            : undefined;
-        const href = '/' + segments.join('/') + '/';
+        const section = parsed.dir && parsed.dir.trim().length > 0 ? parsed.dir.split(path.sep)[0] : undefined;
+        const href = `/${segments.join('/')}/`;
         const title = resolveTitle(frontmatter, content, segments);
         const order = frontmatter.order;
         const baseEntry = {
             path: href,
             title,
             section,
-            order
+            order,
         };
         const merged = applySidebarOverride(baseEntry, overrides);
         if (merged) {
@@ -287,10 +270,7 @@ async function collectContentSearchEntries(context) {
     const { config } = context;
     const contentRoot = config.paths.src.content;
     const overrides = await loadSidebarOverrides(contentRoot);
-    const files = await glob('**/*.md', {
-        cwd: contentRoot,
-        nodir: true
-    });
+    const files = await scanGlob('**/*.md', { cwd: contentRoot });
     if (files.length === 0) {
         return [];
     }
@@ -300,7 +280,7 @@ async function collectContentSearchEntries(context) {
         const markdown = await readFile(sourcePath);
         const { frontmatter, content } = extractFrontmatter(markdown);
         const segments = resolveDocsSegments(relative);
-        const href = '/' + segments.join('/') + '/';
+        const href = `/${segments.join('/')}/`;
         const rawTitle = resolveTitle(frontmatter, content, segments);
         const title = applySidebarTitleOverride(href, rawTitle, overrides);
         if (!title) {
@@ -320,7 +300,7 @@ async function collectContentSearchEntries(context) {
             description: frontmatter.description?.trim() ? frontmatter.description.trim() : undefined,
             headings,
             excerpt,
-            kind: 'docs'
+            kind: 'docs',
         });
     }
     entries.sort((a, b) => a.path.localeCompare(b.path));
@@ -357,7 +337,7 @@ async function loadSidebarOverrides(contentRoot) {
             map.set(normalized, {
                 ...entry,
                 path: normalized,
-                order: defaultOrder
+                order: defaultOrder,
             });
         }
         return map;
@@ -367,14 +347,22 @@ async function loadSidebarOverrides(contentRoot) {
             if (!value || typeof value !== 'object') {
                 continue;
             }
-            const rawPath = typeof value.path === 'string' ? String(value.path) : key;
+            const rawPath = typeof value.path === 'string'
+                ? String(value.path)
+                : key;
             const normalized = normalizeDocsOverrideHref(rawPath);
             if (!normalized) {
                 continue;
             }
-            const title = typeof value.title === 'string' ? String(value.title) : undefined;
-            const section = typeof value.section === 'string' ? String(value.section) : undefined;
-            const hidden = typeof value.hidden === 'boolean' ? Boolean(value.hidden) : undefined;
+            const title = typeof value.title === 'string'
+                ? String(value.title)
+                : undefined;
+            const section = typeof value.section === 'string'
+                ? String(value.section)
+                : undefined;
+            const hidden = typeof value.hidden === 'boolean'
+                ? Boolean(value.hidden)
+                : undefined;
             const orderValue = value.order;
             const order = typeof orderValue === 'number' && Number.isFinite(orderValue) ? orderValue : undefined;
             map.set(normalized, { path: normalized, title, section, hidden, order });
@@ -382,6 +370,12 @@ async function loadSidebarOverrides(contentRoot) {
     }
     return map;
 }
+function isSidebarOverrideChange(context, contentRoot) {
+    if (!context.changedFile) {
+        return false;
+    }
+    return (path.resolve(context.changedFile) === path.join(path.resolve(contentRoot), '_sidebar.json'));
+}
 function applySidebarOverride(entry, overrides) {
     const key = normalizeDocsOverrideHref(entry.path);
     const override = key ? overrides.get(key) : undefined;
@@ -391,14 +385,20 @@ function applySidebarOverride(entry, overrides) {
     if (override.hidden === true) {
         return null;
     }
-    const title = typeof override.title === 'string' && override.title.trim().length > 0 ? override.title.trim() : entry.title;
-    const section = typeof override.section === 'string' && override.section.trim().length > 0 ? override.section.trim() : entry.section;
-    const order = typeof override.order === 'number' && Number.isFinite(override.order) ? override.order : entry.order;
+    const title = typeof override.title === 'string' && override.title.trim().length > 0
+        ? override.title.trim()
+        : entry.title;
+    const section = typeof override.section === 'string' && override.section.trim().length > 0
+        ? override.section.trim()
+        : entry.section;
+    const order = typeof override.order === 'number' && Number.isFinite(override.order)
+        ? override.order
+        : entry.order;
     return {
         path: entry.path,
         title,
         section,
-        order
+        order,
     };
 }
 function applySidebarTitleOverride(href, fallbackTitle, overrides) {
@@ -410,7 +410,9 @@ function applySidebarTitleOverride(href, fallbackTitle, overrides) {
     if (override.hidden === true) {
         return null;
     }
-    const title = typeof override.title === 'string' && override.title.trim().length > 0 ? override.title.trim() : fallbackTitle;
+    const title = typeof override.title === 'string' && override.title.trim().length > 0
+        ? override.title.trim()
+        : fallbackTitle;
     return title;
 }
 function normalizeDocsOverrideHref(value) {
@@ -444,13 +446,14 @@ async function collectPageSearchEntries(context) {
         const titleFromTag = document('title').first().text().trim();
         const titleFromH1 = document('h1').first().text().trim();
         const title = titleFromTag || titleFromH1 || toTitleCase(page.name);
-        const description = document('meta[name="description"]').first().attr('content')?.trim()
-            || undefined;
+        const description = document('meta[name="description"]').first().attr('content')?.trim() || undefined;
         const headings = document('h2, h3')
             .toArray()
             .map((element) => document(element).text().trim())
             .filter((text) => text.length > 0);
-        const mainText = (document('main').first().text() || document.text()).replace(/\s+/g, ' ').trim();
+        const mainText = (document('main').first().text() || document.text())
+            .replace(/\s+/g, ' ')
+            .trim();
         const excerpt = mainText.length > 240 ? `${mainText.slice(0, 240).trim()}…` : mainText;
         entries.push({
             path: resolvePageHref(page.name),
@@ -458,7 +461,7 @@ async function collectPageSearchEntries(context) {
             description,
             headings,
             excerpt,
-            kind: 'page'
+            kind: 'page',
         });
     }
     entries.sort((a, b) => a.path.localeCompare(b.path));
@@ -534,7 +537,7 @@ function extractFrontmatter(markdown) {
     return { frontmatter, content };
 }
 function resolveTitle(frontmatter, content, segments) {
-    if (frontmatter.title && frontmatter.title.trim()) {
+    if (frontmatter.title?.trim()) {
         return frontmatter.title.trim();
     }
     const headingMatch = content.match(/^#\s+(.+)$/m);
@@ -568,7 +571,7 @@ function mergeContentIntoTemplate(appHtml, pageName, bodyHtml, description, enab
     if (main.length === 0 || head.length === 0) {
         throw new Error('Base application template for content pages must include <head> and <main> elements.');
     }
-    if (description && description.trim()) {
+    if (description?.trim()) {
         const meta = head.find('meta[name="description"]').first();
         if (meta.length > 0) {
             meta.attr('content', description.trim());
@@ -581,8 +584,11 @@ function mergeContentIntoTemplate(appHtml, pageName, bodyHtml, description, enab
     const effectiveDescription = (description ?? '').trim() || defaultDescription;
     // Ensure content pages load the shared app styles.
     const cssHref = `/${FOLDERS.app}/app.css`;
-    const existingStylesheet = head.find(`link[rel="stylesheet"][href="${cssHref}"]`).first().length > 0
-        || head.find('link[rel="stylesheet"]').toArray().some((element) => {
+    const existingStylesheet = head.find(`link[rel="stylesheet"][href="${cssHref}"]`).first().length > 0 ||
+        head
+            .find('link[rel="stylesheet"]')
+            .toArray()
+            .some((element) => {
             const href = document(element).attr('href');
             return typeof href === 'string' && href.includes('/app/app.css');
         });
@@ -591,8 +597,11 @@ function mergeContentIntoTemplate(appHtml, pageName, bodyHtml, description, enab
     }
     // Ensure docs pages load the docs layout styles.
     const docsCssHref = resolvePageAssetUrl(pagesUrlPrefix, 'docs', `${FILES.index}${EXTENSIONS.css}`);
-    const existingDocsStylesheet = head.find(`link[rel="stylesheet"][href="${docsCssHref}"]`).first().length > 0
-        || head.find('link[rel="stylesheet"]').toArray().some((element) => {
+    const existingDocsStylesheet = head.find(`link[rel="stylesheet"][href="${docsCssHref}"]`).first().length > 0 ||
+        head
+            .find('link[rel="stylesheet"]')
+            .toArray()
+            .some((element) => {
             const href = document(element).attr('href');
             return typeof href === 'string' && href.includes('/docs/index.css');
         });
@@ -646,7 +655,7 @@ function mergeContentIntoTemplate(appHtml, pageName, bodyHtml, description, enab
             '      </div>',
             '    </div>',
             '  </div>',
-            '</section>'
+            '</section>',
         ].join('\n')
         : [
             '<section class="docs-layout" data-scope="docs">',
@@ -655,7 +664,7 @@ function mergeContentIntoTemplate(appHtml, pageName, bodyHtml, description, enab
             `      <article class="docs-article ws-markdown">${bodyHtml}</article>`,
             '    </div>',
             '  </div>',
-            '</section>'
+            '</section>',
         ].join('\n');
     main.html(docsLayoutHtml);
     return document.root().html() ?? '';
@@ -689,7 +698,7 @@ function buildContentNavTree(entries) {
         title: 'Docs',
         children: [],
         isPage: false,
-        position: position++
+        position: position++,
     };
     for (const entry of entries) {
         const normalizedPath = normalizeDocsPath(entry.path);
@@ -709,7 +718,7 @@ function buildContentNavTree(entries) {
                     title: toTitleCase(segment.replace(/[-_]/g, ' ')),
                     children: [],
                     isPage: false,
-                    position: position++
+                    position: position++,
                 };
                 current.children.push(child);
             }
@@ -734,9 +743,7 @@ function renderContentNavList(nodes, currentPath, depth = 0) {
         const label = node.isPage
             ? `<a class="docs-nav__link" href="${node.path}"${isActive ? ' aria-current="page"' : ''}>${escapeHtml(node.title)}</a>`
             : `<span class="docs-nav__label">${escapeHtml(node.title)}</span>`;
-        const nested = node.children.length > 0
-            ? renderContentNavList(node.children, currentPath, depth + 1)
-            : '';
+        const nested = node.children.length > 0 ? renderContentNavList(node.children, currentPath, depth + 1) : '';
         return `<li class="docs-nav__item"${activeAttr}>${label}${nested}</li>`;
     });
     return `<ol class="${listClass}">${items.join('')}</ol>`;
@@ -748,7 +755,10 @@ function renderContentBreadcrumb(titleByPath, currentPath) {
     const crumbs = [];
     const rootTitle = titleByPath.get('/docs/') ?? 'Docs';
     crumbs.push({ title: rootTitle, href: '/docs/' });
-    const segments = currentPath.replace(/^\/docs\/?/, '').split('/').filter(Boolean);
+    const segments = currentPath
+        .replace(/^\/docs\/?/, '')
+        .split('/')
+        .filter(Boolean);
     let href = '/docs/';
     for (const segment of segments) {
         href = `${href}${segment}/`;
@@ -784,7 +794,7 @@ function ensureMetaName(head, name, content) {
 async function renderMarkdownDoc(markdown) {
     const renderer = getMarkdownRenderer();
     const expanded = await expandAdmonitions(markdown, renderer);
-    const rawHtml = await marked.parse(expanded, { renderer: renderer });
+    const rawHtml = await marked.parse(expanded, { renderer });
     const linked = rewriteMarkdownLinks(rawHtml);
     const { html, headingIds } = ensureHeadingIds(linked);
     return { html, headingIds };
@@ -821,7 +831,7 @@ const ADMONITION_TITLES = {
     tip: 'Tip',
     info: 'Info',
     warning: 'Warning',
-    danger: 'Danger'
+    danger: 'Danger',
 };
 async function expandAdmonitions(markdown, renderer) {
     const lines = markdown.split(/\r?\n/);
@@ -856,18 +866,22 @@ async function expandAdmonitions(markdown, renderer) {
             break;
         }
         const bodyMarkdown = inner.join('\n').trim();
-        const bodyHtml = bodyMarkdown.length > 0 ? await marked.parse(bodyMarkdown, { renderer: renderer }) : '';
+        const bodyHtml = bodyMarkdown.length > 0 ? await marked.parse(bodyMarkdown, { renderer }) : '';
         out.push([
             `<aside class="docs-callout docs-callout--${kindRaw}">`,
             `  <div class="docs-callout__title">${escapeHtml(title)}</div>`,
             `  <div class="docs-callout__body">${bodyHtml}</div>`,
-            `</aside>`
+            `</aside>`,
         ].join('\n'));
     }
     return out.join('\n');
 }
 function isAdmonitionKind(value) {
-    return value === 'note' || value === 'tip' || value === 'info' || value === 'warning' || value === 'danger';
+    return (value === 'note' ||
+        value === 'tip' ||
+        value === 'info' ||
+        value === 'warning' ||
+        value === 'danger');
 }
 function ensureHeadingIds(html) {
     const document = load(html);
@@ -928,9 +942,9 @@ function validateRenderedContentPages(pages) {
             if (!resolved) {
                 continue;
             }
-            const isDocsPage = resolved.pathname === '/docs'
-                || resolved.pathname === '/docs/'
-                || resolved.pathname.startsWith('/docs/');
+            const isDocsPage = resolved.pathname === '/docs' ||
+                resolved.pathname === '/docs/' ||
+                resolved.pathname.startsWith('/docs/');
             if (!isDocsPage) {
                 continue;
             }
@@ -995,21 +1009,19 @@ async function rewriteContentForPublish(html, shared, docsManifest, options) {
         document(`link[href="/app/app.css"]`).attr('href', `/app/${shared.css}`);
     }
     if (shared?.js) {
-        document(`script[src="/app/app.js"]`)
-            .attr('src', `/app/${shared.js}`)
-            .attr('type', 'module');
+        document(`script[src="/app/app.js"]`).attr('src', `/app/${shared.js}`).attr('type', 'module');
     }
     if (docsManifest.css) {
         const selector = [
             `link[href="${resolvePageAssetUrl(pagesUrlPrefix, 'docs', `${FILES.index}${EXTENSIONS.css}`)}"]`,
-            `link[href="${resolvePageAssetUrl(buildPagesUrlPrefix, 'docs', `${FILES.index}${EXTENSIONS.css}`)}"]`
+            `link[href="${resolvePageAssetUrl(buildPagesUrlPrefix, 'docs', `${FILES.index}${EXTENSIONS.css}`)}"]`,
         ].join(', ');
         document(selector).attr('href', resolvePageAssetUrl(pagesUrlPrefix, 'docs', docsManifest.css));
     }
     if (docsManifest.js) {
         const selector = [
             `script[src="${resolvePageAssetUrl(pagesUrlPrefix, 'docs', `${FILES.index}${EXTENSIONS.js}`)}"]`,
-            `script[src="${resolvePageAssetUrl(buildPagesUrlPrefix, 'docs', `${FILES.index}${EXTENSIONS.js}`)}"]`
+            `script[src="${resolvePageAssetUrl(buildPagesUrlPrefix, 'docs', `${FILES.index}${EXTENSIONS.js}`)}"]`,
         ].join(', ');
         document(selector)
             .attr('src', resolvePageAssetUrl(pagesUrlPrefix, 'docs', docsManifest.js))