@abreen/tada 1.0.0

package/webpack/reachability.js

@@ -0,0 +1,273 @@
+const path = require('path');
+const { JSDOM } = require('jsdom');
+
+function stripQueryAndHash(href) {
+  return href.split('#')[0].split('?')[0];
+}
+
+function isExternalOrAnchor(href) {
+  if (!href || href.startsWith('#') || href.startsWith('//')) {
+    return true;
+  }
+
+  return /^[a-zA-Z][a-zA-Z\d+.-]*:/.test(href);
+}
+
+function normalizeUrlPath(pathname) {
+  const normalized = path.posix.normalize(pathname);
+  if (normalized === '.' || normalized === '') {
+    return '/';
+  }
+
+  return normalized.startsWith('/') ? normalized : `/${normalized}`;
+}
+
+function stripBasePath(pathname, basePath) {
+  const normalizedPath = normalizeUrlPath(pathname);
+  const normalizedBasePath = normalizeUrlPath(basePath || '/');
+
+  if (normalizedBasePath === '/') {
+    return normalizedPath;
+  }
+
+  if (normalizedPath === normalizedBasePath) {
+    return '/';
+  }
+
+  const prefix = `${normalizedBasePath}/`;
+  if (normalizedPath.startsWith(prefix)) {
+    return normalizeUrlPath(normalizedPath.slice(normalizedBasePath.length));
+  }
+
+  return normalizedPath;
+}
+
+function toCandidateAssetPaths(urlPath) {
+  const normalizedPath = normalizeUrlPath(urlPath);
+
+  if (normalizedPath === '/') {
+    return ['index.html'];
+  }
+
+  if (normalizedPath.endsWith('.html')) {
+    return [normalizedPath.slice(1)];
+  }
+
+  if (path.posix.extname(normalizedPath)) {
+    return [];
+  }
+
+  const withoutLeadingSlash = normalizedPath.slice(1);
+  if (normalizedPath.endsWith('/')) {
+    return [`${withoutLeadingSlash}index.html`];
+  }
+
+  return [`${withoutLeadingSlash}/index.html`, `${withoutLeadingSlash}.html`];
+}
+
+function resolveInternalPath({ href, fromAssetPath, basePath = '/' }) {
+  if (!href) {
+    return null;
+  }
+
+  const trimmedHref = href.trim();
+  if (!trimmedHref || isExternalOrAnchor(trimmedHref)) {
+    return null;
+  }
+
+  const pathname = stripQueryAndHash(trimmedHref);
+  if (!pathname) {
+    return null;
+  }
+
+  let resolvedPath = pathname.startsWith('/')
+    ? stripBasePath(pathname, basePath)
+    : normalizeUrlPath(
+        path.posix.join(path.posix.dirname(`/${fromAssetPath}`), pathname),
+      );
+
+  try {
+    return normalizeUrlPath(decodeURIComponent(resolvedPath));
+  } catch {
+    return normalizeUrlPath(resolvedPath);
+  }
+}
+
+function resolveHrefToHtmlAssetPath({
+  href,
+  fromAssetPath,
+  basePath = '/',
+  knownAssets,
+}) {
+  const decodedPath = resolveInternalPath({ href, fromAssetPath, basePath });
+  if (!decodedPath) {
+    return null;
+  }
+
+  for (const candidate of toCandidateAssetPaths(decodedPath)) {
+    if (knownAssets.has(candidate)) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+function resolveHrefToPdfPath({
+  href,
+  fromAssetPath,
+  basePath = '/',
+  knownPdfPaths,
+}) {
+  const decodedPath = resolveInternalPath({ href, fromAssetPath, basePath });
+  if (!decodedPath || !decodedPath.toLowerCase().endsWith('.pdf')) {
+    return null;
+  }
+
+  return knownPdfPaths.has(decodedPath) ? decodedPath : null;
+}
+
+function collectDirectSiteAssetLinks({
+  html,
+  fromAssetPath,
+  knownAssets,
+  knownPdfPaths = new Set(),
+  basePath = '/',
+}) {
+  const htmlAssetPaths = new Set();
+  const pdfPaths = new Set();
+  const dom = new JSDOM(html);
+
+  try {
+    const links = dom.window.document.querySelectorAll('a');
+    for (const link of links) {
+      if (link.classList.contains('disabled')) {
+        continue;
+      }
+
+      const href = link.getAttribute('href');
+      const pdfPath = resolveHrefToPdfPath({
+        href,
+        fromAssetPath,
+        basePath,
+        knownPdfPaths,
+      });
+      if (pdfPath) {
+        pdfPaths.add(pdfPath);
+      }
+
+      const targetPath = resolveHrefToHtmlAssetPath({
+        href,
+        fromAssetPath,
+        basePath,
+        knownAssets,
+      });
+      if (targetPath) {
+        htmlAssetPaths.add(targetPath);
+      }
+    }
+
+    const refreshTarget = getMetaRefreshTarget(dom.window.document);
+    if (refreshTarget) {
+      const targetPath = resolveHrefToHtmlAssetPath({
+        href: refreshTarget,
+        fromAssetPath,
+        basePath,
+        knownAssets,
+      });
+      if (targetPath) {
+        htmlAssetPaths.add(targetPath);
+      }
+    }
+  } finally {
+    dom.window.close();
+  }
+
+  return {
+    htmlAssetPaths: [...htmlAssetPaths].sort(),
+    pdfPaths: [...pdfPaths].sort(),
+  };
+}
+
+function collectReachableSiteAssets({
+  htmlAssetsByPath,
+  knownPdfPaths = new Set(),
+  rootPath = 'index.html',
+  basePath = '/',
+}) {
+  if (!htmlAssetsByPath.has(rootPath)) {
+    throw new Error(`Pagefind reachability root not found: ${rootPath}`);
+  }
+
+  const knownAssets = new Set(htmlAssetsByPath.keys());
+  const reachable = new Set();
+  const reachablePdfPaths = new Set();
+  const pending = [rootPath];
+
+  while (pending.length > 0) {
+    const currentPath = pending.pop();
+    if (reachable.has(currentPath)) {
+      continue;
+    }
+    reachable.add(currentPath);
+
+    const html = htmlAssetsByPath.get(currentPath);
+    const { htmlAssetPaths, pdfPaths } = collectDirectSiteAssetLinks({
+      html,
+      fromAssetPath: currentPath,
+      knownAssets,
+      knownPdfPaths,
+      basePath,
+    });
+
+    for (const pdfPath of pdfPaths) {
+      reachablePdfPaths.add(pdfPath);
+    }
+
+    for (const targetPath of htmlAssetPaths) {
+      if (!reachable.has(targetPath)) {
+        pending.push(targetPath);
+      }
+    }
+  }
+
+  return {
+    reachableHtmlPaths: [...reachable].sort(),
+    reachablePdfPaths: [...reachablePdfPaths].sort(),
+  };
+}
+
+function collectReachableHtmlAssets(options) {
+  return collectReachableSiteAssets(options).reachableHtmlPaths;
+}
+
+function getMetaRefreshTarget(document) {
+  const refreshTags = document.querySelectorAll('meta[http-equiv]');
+  for (const tag of refreshTags) {
+    const httpEquiv = tag.getAttribute('http-equiv');
+    if (!httpEquiv || httpEquiv.toLowerCase() !== 'refresh') {
+      continue;
+    }
+
+    const content = tag.getAttribute('content') || '';
+    const match = content.match(/(?:^|;)\s*url\s*=\s*(.+)\s*$/i);
+    if (!match) {
+      continue;
+    }
+
+    const target = match[1].trim().replace(/^['"]|['"]$/g, '');
+    if (target) {
+      return target;
+    }
+  }
+
+  return null;
+}
+
+module.exports = {
+  collectDirectSiteAssetLinks,
+  collectReachableHtmlAssets,
+  collectReachableSiteAssets,
+  resolveHrefToHtmlAssetPath,
+  resolveHrefToPdfPath,
+};

package/webpack/reachability.test.js

@@ -0,0 +1,80 @@
+const { describe, expect, test } = require('bun:test');
+const {
+  collectDirectSiteAssetLinks,
+  collectReachableSiteAssets,
+} = require('./reachability');
+
+describe('reachability', () => {
+  test('collectDirectSiteAssetLinks resolves relative links and ignores excluded links', () => {
+    const result = collectDirectSiteAssetLinks({
+      html: `
+        <a href="../guide.html?x=1#top">Guide</a>
+        <a class="disabled" href="/ignore/">Ignore</a>
+        <a href="https://example.com/">External</a>
+        <a href="#section">Anchor</a>
+        <a href="mailto:test@example.com">Mail</a>
+        <a href="/docs/guide.pdf#page=2">PDF</a>
+      `,
+      fromAssetPath: 'section/index.html',
+      knownAssets: new Set(['guide.html', 'ignore/index.html']),
+      knownPdfPaths: new Set(['/docs/guide.pdf']),
+      basePath: '/',
+    });
+
+    expect(result).toEqual({
+      htmlAssetPaths: ['guide.html'],
+      pdfPaths: ['/docs/guide.pdf'],
+    });
+  });
+
+  test('collectDirectSiteAssetLinks honors basePath and meta refresh', () => {
+    const result = collectDirectSiteAssetLinks({
+      html: `
+        <a href="/course/faq/">FAQ</a>
+        <meta http-equiv="refresh" content="0; url='/course/refresh/'" />
+      `,
+      fromAssetPath: 'index.html',
+      knownAssets: new Set(['faq/index.html', 'refresh/index.html']),
+      basePath: '/course',
+    });
+
+    expect(result).toEqual({
+      htmlAssetPaths: ['faq/index.html', 'refresh/index.html'],
+      pdfPaths: [],
+    });
+  });
+
+  test('collectReachableSiteAssets reuses direct link parsing for html and pdf reachability', () => {
+    const htmlAssetsByPath = new Map([
+      [
+        'index.html',
+        `
+          <a href="/about/">About</a>
+          <a href="/docs/guide.pdf">Guide PDF</a>
+        `,
+      ],
+      [
+        'about/index.html',
+        `<meta http-equiv="refresh" content="0; url='/redirect/'" />`,
+      ],
+      ['redirect/index.html', '<p>Done</p>'],
+      ['orphan/index.html', '<p>Orphan</p>'],
+    ]);
+
+    const result = collectReachableSiteAssets({
+      htmlAssetsByPath,
+      knownPdfPaths: new Set(['/docs/guide.pdf']),
+      rootPath: 'index.html',
+      basePath: '/',
+    });
+
+    expect(result).toEqual({
+      reachableHtmlPaths: [
+        'about/index.html',
+        'index.html',
+        'redirect/index.html',
+      ],
+      reachablePdfPaths: ['/docs/guide.pdf'],
+    });
+  });
+});

package/webpack/serve.js

@@ -0,0 +1,104 @@
+const fs = require('fs');
+const path = require('path');
+const { getDistDir } = require('./util');
+const { makeLogger } = require('./log');
+const { B } = require('./colors');
+
+const log = makeLogger(__filename);
+
+function messageReady(port) {
+  if (process.send) {
+    process.send({ ready: true, port });
+  }
+}
+
+let distDir;
+try {
+  distDir = getDistDir();
+} catch (err) {
+  log.error`Failed to start server: ${err}`;
+  process.exit(1);
+}
+
+function resolvePathname(pathname) {
+  let decodedPath;
+  try {
+    decodedPath = decodeURIComponent(pathname);
+  } catch {
+    return null;
+  }
+
+  const resolvedPath = path.resolve(distDir, '.' + decodedPath);
+  const relativePath = path.relative(distDir, resolvedPath);
+  if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+    return null;
+  }
+
+  let stat;
+  try {
+    stat = fs.statSync(resolvedPath);
+  } catch {
+    return null;
+  }
+
+  if (stat.isDirectory()) {
+    return null;
+  }
+
+  if (!stat.isFile()) {
+    return null;
+  }
+
+  return resolvedPath;
+}
+
+function createResponse(req) {
+  const url = new URL(req.url);
+  const filePath = resolvePathname(url.pathname);
+  if (!filePath) {
+    return new Response('Not Found', { status: 404 });
+  }
+
+  return new Response(Bun.file(filePath));
+}
+
+function tryListen(port, fallbackPort) {
+  return new Promise((resolve, reject) => {
+    try {
+      const server = Bun.serve({
+        port,
+        fetch: createResponse,
+        error(error) {
+          log.error`Request failed: ${error}`;
+          return new Response('Internal Server Error', { status: 500 });
+        },
+      });
+
+      log.info`Dev server: ${B`http://localhost:${server.port}/index.html`}`;
+      messageReady(server.port);
+      resolve(server);
+    } catch (err) {
+      if (err.code === 'EADDRINUSE' && fallbackPort) {
+        log.warn`Port ${port} in use, trying fallback ${fallbackPort}...`;
+        return tryListen(fallbackPort, null).then(resolve).catch(reject);
+      }
+
+      reject(err);
+    }
+  });
+}
+
+tryListen(8080, 8081).catch(err => {
+  log.error`Failed to start server: ${err}`;
+  process.exit(1);
+});
+
+process.on('uncaughtException', err => {
+  log.error`Uncaught exception: ${err}`;
+  process.exit(1);
+});
+
+process.on('unhandledRejection', reason => {
+  log.error`Unhandled rejection: ${reason}`;
+  process.exit(1);
+});

package/webpack/site-variables.js

@@ -0,0 +1,53 @@
+const fs = require('fs');
+const path = require('path');
+const { compile: compileJsonSchema, doValidation } = require('./json-schema');
+const { getProjectDir } = require('./utils/paths');
+const configDir = path.resolve(getProjectDir(), 'config');
+
+const DEFAULT = { basePath: '/', features: { search: true, code: true } };
+
+const isValid = compileJsonSchema(require('./site.schema.json'));
+
+function getJson(filePath) {
+  return JSON.parse(
+    fs.readFileSync(path.resolve(configDir, filePath), 'utf-8'),
+  );
+}
+
+function getSiteVariables(env) {
+  const fileName = `site.${env}.json`;
+  const fromFile = getJson(fileName);
+  const variables = {
+    ...DEFAULT,
+    ...fromFile,
+    features: { ...DEFAULT.features, ...(fromFile.features || {}) },
+  };
+
+  // Derive faviconSymbol from symbol if not explicitly set
+  if (variables.symbol && !variables.faviconSymbol) {
+    variables.faviconSymbol = variables.symbol;
+  }
+
+  // Derive faviconColor from themeColor if not explicitly set
+  if (variables.themeColor && !variables.faviconColor) {
+    variables.faviconColor = variables.themeColor;
+  }
+
+  // Derive titlePostfix from title if not explicitly set
+  if (variables.title && !variables.titlePostfix) {
+    variables.titlePostfix = ` - ${variables.title}`;
+  }
+
+  doValidation(isValid, variables, fileName);
+  return variables;
+}
+
+function getDevSiteVariables() {
+  return getSiteVariables('dev');
+}
+
+function getProdSiteVariables() {
+  return getSiteVariables('prod');
+}
+
+module.exports = { getDevSiteVariables, getProdSiteVariables };

package/webpack/site.schema.json

@@ -0,0 +1,67 @@
+{
+  "type": "object",
+  "required": ["defaultTimeZone"],
+  "properties": {
+    "features": {
+      "type": "object",
+      "default": { "search": true, "code": true },
+      "properties": {
+        "search": { "type": "boolean", "default": true },
+        "code": { "type": "boolean", "default": true },
+        "favicon": { "type": "boolean", "default": false },
+        "literateJava": { "type": "boolean", "default": false }
+      },
+      "required": ["search", "code", "favicon"],
+      "additionalProperties": false
+    },
+    "base": { "type": "string", "pattern": "^https?:\\/\\/[-.:a-zA-Z0-9]+$" },
+    "basePath": {
+      "type": "string",
+      "default": "/",
+      "pattern": "^\\/[-a-zA-Z0-9]*?$"
+    },
+    "internalDomains": {
+      "type": "array",
+      "default": [],
+      "items": { "type": "string", "pattern": "^[-.:a-zA-Z0-9]+$" }
+    },
+    "title": { "type": "string" },
+    "symbol": { "type": "string", "pattern": "^[A-Z0-9\\- ]{1,5}$" },
+    "titlePostfix": { "type": "string" },
+    "courseId": { "type": "string" },
+    "themeColor": {
+      "type": "string",
+      "pattern": "^hsl\\(\\d+(deg)? \\d+% \\d+%\\)$"
+    },
+    "tintHue": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 360,
+      "default": 20
+    },
+    "tintAmount": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 100,
+      "default": 100
+    },
+    "faviconColor": {
+      "type": "string",
+      "pattern": "^hsl\\(\\d+(deg)? \\d+% \\d+%\\)$"
+    },
+    "faviconSymbol": { "type": "string", "pattern": "^[A-Z0-9\\- ]{1,5}$" },
+    "faviconFontWeight": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 1000,
+      "default": 700
+    },
+    "defaultTimeZone": { "type": "string" },
+    "vars": { "type": "object" },
+    "codeLanguages": {
+      "type": "object",
+      "additionalProperties": { "type": "string" }
+    }
+  },
+  "additionalProperties": false
+}

package/webpack/templates.js

@@ -0,0 +1,128 @@
+const fs = require('fs');
+const path = require('path');
+const _ = require('lodash');
+const { compile: compileJsonSchema, doValidation } = require('./json-schema');
+const { makeLogger } = require('./log');
+
+const log = makeLogger(__filename);
+
+// Store all templates in memory (don't read template files during build)
+const templates = {};
+
+// All parsed data (from .json files)
+const jsonData = {};
+
+// Compiled JSON Schema for the .json files
+const validators = {};
+
+// Keeps track of template call tree
+const renderStack = [];
+let errorStack = null;
+
+// JSON data files that live in the user's config directory
+const JSON_DATA_FILES = ['nav.json', 'authors.json'];
+
+function getHtmlTemplatesDir() {
+  const { getPackageDir } = require('./utils/paths');
+  return path.resolve(getPackageDir(), 'templates');
+}
+
+function getJsonDataDir() {
+  const { getConfigDir } = require('./utils/paths');
+  return getConfigDir();
+}
+
+function json(fileName) {
+  return jsonData[fileName];
+}
+
+function render(fileName, params) {
+  if (params != null) {
+    // Allow the template to call render(), it will use our params
+    params.render = otherFileName => render(otherFileName, params);
+
+    // Allow the template to read the JSON files we previously read into memory
+    params.json = json;
+  }
+
+  renderStack.push(fileName);
+  try {
+    return _.template(templates[fileName])(params);
+  } catch (err) {
+    if (errorStack == null) {
+      errorStack = renderStack.slice();
+
+      if (renderStack.length > 1) {
+        throw err;
+      }
+    } else if (renderStack.length === 1) {
+      const topItem = errorStack[errorStack.length - 1];
+      throw new Error(`Render error in ${topItem}: ${err}`);
+    }
+  } finally {
+    renderStack.pop();
+  }
+}
+
+function compileTemplates(siteVariables) {
+  log.info`Compiling templates`;
+
+  Object.keys(templates).forEach(k => delete templates[k]);
+  Object.keys(jsonData).forEach(k => delete jsonData[k]);
+
+  // Load HTML templates from the package
+  const htmlDir = getHtmlTemplatesDir();
+  fs.readdirSync(htmlDir).forEach(fileName => {
+    const ext = path.extname(fileName).toLowerCase();
+    if (ext === '.html') {
+      log.debug`Reading ${fileName}`;
+      templates[fileName] = fs.readFileSync(
+        path.join(htmlDir, fileName),
+        'utf-8',
+      );
+    }
+  });
+
+  // Load JSON data files from the project's config directory
+  const jsonDir = getJsonDataDir();
+  for (const fileName of JSON_DATA_FILES) {
+    const filePath = path.join(jsonDir, fileName);
+    if (!fs.existsSync(filePath)) {
+      throw new Error(`Missing required data file: ${filePath}`);
+    }
+
+    // Schema validation (schemas live in the package templates dir)
+    const schemaFile = `${path.parse(fileName).name}.schema.json`;
+    const schemaPath = path.join(htmlDir, schemaFile);
+    if (!fs.existsSync(schemaPath)) {
+      throw new Error(`Missing JSON Schema for ${fileName}: ${schemaPath}`);
+    }
+    compileAndSetValidator(schemaPath, fileName);
+
+    log.debug`Reading ${fileName}`;
+    jsonData[fileName] = JSON.parse(
+      _.template(fs.readFileSync(filePath, 'utf-8'))({
+        ...(siteVariables.vars || {}),
+        site: siteVariables,
+        base: siteVariables.base,
+        basePath: siteVariables.basePath,
+      }),
+    );
+
+    doValidation(validators[fileName], jsonData[fileName], fileName);
+  }
+}
+
+function compileAndSetValidator(schemaPath, fileName) {
+  const schema = JSON.parse(fs.readFileSync(schemaPath, 'utf-8'));
+  validators[fileName] = compileJsonSchema(schema);
+}
+
+module.exports = {
+  compileTemplates,
+  render,
+  getHtmlTemplatesDir,
+  getJsonDataDir,
+  json,
+  JSON_DATA_FILES,
+};