@abreen/tada 1.0.0

package/webpack/build-state.js

@@ -0,0 +1,97 @@
+const watchStateByCompiler = new WeakMap();
+const buildDeltaByCompiler = new WeakMap();
+
+function cloneSet(values) {
+  return new Set(values || []);
+}
+
+function getEmptyBuildDelta() {
+  return {
+    changedSourceFiles: new Set(),
+    changedHtmlAssetPaths: new Set(),
+    removedHtmlAssetPaths: new Set(),
+    templatesChanged: false,
+  };
+}
+
+function setWatchState(compiler, watchState) {
+  watchStateByCompiler.set(compiler, {
+    contentFiles: cloneSet(watchState?.contentFiles),
+    buildContentFiles: cloneSet(watchState?.buildContentFiles),
+    changedContentFiles: cloneSet(watchState?.changedContentFiles),
+    templatesChanged: Boolean(watchState?.templatesChanged),
+    structureChanged: Boolean(watchState?.structureChanged),
+  });
+}
+
+function getWatchState(compiler) {
+  const state = watchStateByCompiler.get(compiler);
+  if (!state) {
+    return null;
+  }
+
+  return {
+    contentFiles: cloneSet(state.contentFiles),
+    buildContentFiles: cloneSet(state.buildContentFiles),
+    changedContentFiles: cloneSet(state.changedContentFiles),
+    templatesChanged: state.templatesChanged,
+    structureChanged: state.structureChanged,
+  };
+}
+
+function setBuildDelta(compiler, buildDelta) {
+  buildDeltaByCompiler.set(compiler, {
+    changedSourceFiles: cloneSet(buildDelta?.changedSourceFiles),
+    changedHtmlAssetPaths: cloneSet(buildDelta?.changedHtmlAssetPaths),
+    removedHtmlAssetPaths: cloneSet(buildDelta?.removedHtmlAssetPaths),
+    templatesChanged: Boolean(buildDelta?.templatesChanged),
+  });
+}
+
+function mergeIntoSet(target, values) {
+  if (!values) {
+    return;
+  }
+
+  for (const value of values) {
+    target.add(value);
+  }
+}
+
+function updateBuildDelta(compiler, buildDelta) {
+  const current = getBuildDelta(compiler);
+  mergeIntoSet(current.changedSourceFiles, buildDelta?.changedSourceFiles);
+  mergeIntoSet(
+    current.changedHtmlAssetPaths,
+    buildDelta?.changedHtmlAssetPaths,
+  );
+  mergeIntoSet(
+    current.removedHtmlAssetPaths,
+    buildDelta?.removedHtmlAssetPaths,
+  );
+  current.templatesChanged =
+    current.templatesChanged || Boolean(buildDelta?.templatesChanged);
+  buildDeltaByCompiler.set(compiler, current);
+}
+
+function getBuildDelta(compiler) {
+  const delta = buildDeltaByCompiler.get(compiler);
+  if (!delta) {
+    return getEmptyBuildDelta();
+  }
+
+  return {
+    changedSourceFiles: cloneSet(delta.changedSourceFiles),
+    changedHtmlAssetPaths: cloneSet(delta.changedHtmlAssetPaths),
+    removedHtmlAssetPaths: cloneSet(delta.removedHtmlAssetPaths),
+    templatesChanged: delta.templatesChanged,
+  };
+}
+
+module.exports = {
+  getBuildDelta,
+  getWatchState,
+  setBuildDelta,
+  setWatchState,
+  updateBuildDelta,
+};

package/webpack/code.test.js

@@ -0,0 +1,162 @@
+const { describe, expect, test, beforeAll } = require('bun:test');
+const { initHighlighter } = require('./utils/shiki-highlighter');
+const {
+  renderCodeWithComments,
+  extractJavaMethodToc,
+} = require('./utils/code');
+
+beforeAll(async () => {
+  await initHighlighter(['java', 'text', 'plaintext']);
+});
+
+describe('extractJavaMethodToc', () => {
+  test('returns methods from a regular class', () => {
+    const toc = extractJavaMethodToc(`
+public class Foo {
+  public void foo() {}
+  public int bar(int x) { return x; }
+}
+`);
+    expect(toc).toEqual([
+      { kind: 'method', label: 'Method', name: 'foo()', line: 3 },
+      { kind: 'method', label: 'Method', name: 'bar(x)', line: 4 },
+    ]);
+  });
+
+  test('returns top-level methods from a compact source file', () => {
+    const toc = extractJavaMethodToc(`
+void hello() {
+  System.out.println("Hello");
+}
+
+void main() {
+  hello();
+}
+`);
+    expect(toc).toEqual([
+      { kind: 'method', label: 'Method', name: 'hello()', line: 2 },
+      { kind: 'method', label: 'Method', name: 'main()', line: 6 },
+    ]);
+  });
+
+  test('returns empty array when class has no methods or fields', () => {
+    const toc = extractJavaMethodToc(`
+public class Empty {
+}
+`);
+    expect(toc).toEqual([]);
+  });
+
+  test('returns constructor from a class', () => {
+    const toc = extractJavaMethodToc(`
+public class Point {
+  public Point(int x) {}
+}
+`);
+    expect(toc).toEqual([
+      { kind: 'constructor', label: 'Constructor', name: 'Point(x)', line: 3 },
+    ]);
+  });
+
+  test('excludes methods on inner classes', () => {
+    const toc = extractJavaMethodToc(`
+public class Outer {
+  public void outerMethod() {}
+  static class Inner {
+    public void innerMethod() {}
+  }
+}
+`);
+    expect(toc.map(e => e.name)).toEqual(['outerMethod()']);
+  });
+
+  test('returns default method from an interface', () => {
+    const toc = extractJavaMethodToc(`
+public interface Greeter {
+  default String greet(String name) { return "Hello, " + name; }
+}
+`);
+    expect(toc).toEqual([
+      { kind: 'method', label: 'Method', name: 'greet(name)', line: 3 },
+    ]);
+  });
+
+  test('returns fields from a class with type but not access modifier', () => {
+    const toc = extractJavaMethodToc(`
+public class Counter {
+  private int count;
+  public String label;
+}
+`);
+    expect(toc.map(e => e.name)).toEqual(['int count', 'String label']);
+  });
+
+  test('returns one entry per variable in a multi-variable declaration', () => {
+    const toc = extractJavaMethodToc(`
+public class Coords {
+  int x, y;
+}
+`);
+    expect(toc.map(e => e.name)).toEqual(['int x', 'int y']);
+  });
+
+  test('returns array type field', () => {
+    const toc = extractJavaMethodToc(`
+public class Arr {
+  int[] values;
+}
+`);
+    expect(toc).toEqual([
+      { kind: 'field', label: 'Field', name: 'int[] values', line: 3 },
+    ]);
+  });
+
+  test('returns generic type field', () => {
+    const toc = extractJavaMethodToc(`
+public class Container {
+  List<String> items;
+}
+`);
+    expect(toc).toEqual([
+      { kind: 'field', label: 'Field', name: 'List<String> items', line: 3 },
+    ]);
+  });
+
+  test('returns interface constant', () => {
+    const toc = extractJavaMethodToc(`
+public interface Config {
+  int TIMEOUT = 30;
+}
+`);
+    expect(toc).toEqual([
+      { kind: 'field', label: 'Field', name: 'int TIMEOUT', line: 3 },
+    ]);
+  });
+
+  test('returns abstract interface methods (no body)', () => {
+    const toc = extractJavaMethodToc(`
+public interface Greeter {
+  String greet(String name);
+}
+`);
+    expect(toc).toEqual([
+      { kind: 'method', label: 'Method', name: 'greet(name)', line: 3 },
+    ]);
+  });
+});
+
+describe('renderCodeWithComments', () => {
+  test('renders build-time line rows for code segments', () => {
+    const html = renderCodeWithComments('alpha\n\nbeta\n', 'java', {
+      basePath: '/',
+      internalDomains: [],
+    });
+
+    expect(html).toContain('<span class="code-row">');
+    expect(html).toContain('id="L1" href="#L1"');
+    expect(html).toContain('id="L2" href="#L2"');
+    expect(html).toContain('id="L3" href="#L3"');
+    expect(html).not.toContain('id="L4" href="#L4"');
+    expect(html).toContain('<code class="shiki language-java">');
+  });
+});

package/webpack/colors.js

@@ -0,0 +1,15 @@
+const util = require('util');
+
+const R = (str, ...args) => util.styleText(['red'], String.raw(str, ...args));
+const G = (str, ...args) => util.styleText(['green'], String.raw(str, ...args));
+const B = (str, ...args) => util.styleText(['blue'], String.raw(str, ...args));
+const Y = (str, ...args) =>
+  util.styleText(['yellow'], String.raw(str, ...args));
+const L = (str, ...args) =>
+  util.styleText(['blackBright'], String.raw(str, ...args));
+const P = (str, ...args) =>
+  util.styleText(['magenta'], String.raw(str, ...args));
+const I = (str, ...args) =>
+  util.styleText(['italic', 'bold'], String.raw(str, ...args));
+
+module.exports = { R, G, B, Y, L, P, I };

package/webpack/config.base.js

@@ -0,0 +1,147 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const _ = require('lodash');
+const CopyPlugin = require('copy-webpack-plugin');
+const MiniCssExtractPlugin = require('mini-css-extract-plugin');
+const GenerateContentAssetsPlugin = require('./generate-content-assets-plugin');
+const PagefindPlugin = require('./pagefind-plugin');
+const GenerateFaviconPlugin = require('./generate-favicon-plugin');
+const GenerateManifestPlugin = require('./generate-manifest-plugin');
+const GenerateFontsPlugin = require('./generate-fonts-plugin');
+const { getDistDir, createDefinePlugin } = require('./util');
+const { isFeatureEnabled } = require('./features');
+const {
+  getContentDir,
+  getPackageDir,
+  getProjectDir,
+  getPublicDir,
+} = require('./utils/paths');
+const { parseHsl } = require('./utils/parse-hsl');
+
+const distDir = getDistDir();
+
+function renderThemeScss(siteVariables) {
+  const templatePath = path.join(getPackageDir(), 'templates/_theme.scss');
+  const template = fs.readFileSync(templatePath, 'utf-8');
+  const { hue, saturation, lightness } = parseHsl(siteVariables.themeColor);
+  const tintHue = siteVariables.tintHue ?? 20;
+  const tintAmount = siteVariables.tintAmount ?? 100;
+  const rendered = _.template(template)({
+    themeHue: hue,
+    themeSaturation: saturation,
+    themeLightness: lightness,
+    tintHue,
+    tintAmount,
+  });
+
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tada-'));
+  const configDir = path.join(tmpDir, 'config');
+  fs.mkdirSync(configDir);
+  fs.writeFileSync(path.join(configDir, '_theme.scss'), rendered);
+
+  return tmpDir;
+}
+
+function createModuleRules(siteVariables) {
+  const packageDir = getPackageDir();
+  const themeDir = renderThemeScss(siteVariables);
+
+  return [
+    { test: /\.js$/, exclude: /node_modules/, use: { loader: 'babel-loader' } },
+    {
+      test: /\.tsx?$/,
+      exclude: /node_modules/,
+      loader: 'ts-loader',
+      options: { configFile: path.resolve(packageDir, 'tsconfig.json') },
+    },
+    {
+      test: /\.(sa|sc|c)ss$/,
+      use: [
+        MiniCssExtractPlugin.loader,
+        {
+          loader: 'css-loader',
+          options: {
+            url: {
+              // Don't bundle fonts (they are handled by GenerateFontsPlugin)
+              filter: url => !url.endsWith('.woff2'),
+            },
+          },
+        },
+        {
+          loader: 'sass-loader',
+          options: { sassOptions: { loadPaths: [themeDir, getProjectDir()] } },
+        },
+      ],
+    },
+  ];
+}
+
+async function createPlugins(
+  siteVariables,
+  { defineIsDev = false, plugins = [] } = {},
+) {
+  return [
+    new GenerateContentAssetsPlugin(siteVariables),
+    createDefinePlugin(siteVariables, defineIsDev),
+    new MiniCssExtractPlugin({
+      filename: '[name].css',
+      chunkFilename: '[id].css',
+    }),
+    new CopyPlugin({
+      patterns: [
+        { from: getPublicDir(), to: '.', noErrorOnMissing: true },
+        {
+          from: '**/*.{png,jpg,jpeg,gif,svg,txt,zip}',
+          context: getContentDir(),
+          to: '[path][name][ext]',
+          noErrorOnMissing: true,
+        },
+      ],
+    }),
+    isFeatureEnabled(siteVariables, 'search')
+      ? new PagefindPlugin(siteVariables)
+      : null,
+    isFeatureEnabled(siteVariables, 'favicon')
+      ? new GenerateFaviconPlugin(siteVariables)
+      : null,
+    isFeatureEnabled(siteVariables, 'favicon')
+      ? new GenerateManifestPlugin(siteVariables)
+      : null,
+    new GenerateFontsPlugin(),
+    ...plugins,
+    require('./print-flair-plugin'),
+  ].filter(Boolean);
+}
+
+async function createBaseConfig({
+  mode,
+  siteVariables,
+  entry,
+  devtool,
+  defineIsDev = false,
+  optimization,
+  plugins,
+}) {
+  const packageDir = getPackageDir();
+  return {
+    mode,
+    entry,
+    output: {
+      path: distDir,
+      publicPath: siteVariables.basePath,
+      filename: '[name].bundle.js',
+    },
+    resolve: { extensions: ['.ts', '.js', '.json'] },
+    resolveLoader: {
+      modules: [path.resolve(packageDir, 'node_modules'), 'node_modules'],
+    },
+    devtool,
+    module: { rules: createModuleRules(siteVariables) },
+    ...(optimization && { optimization }),
+    plugins: await createPlugins(siteVariables, { defineIsDev, plugins }),
+    stats: 'errors-only',
+  };
+}
+
+module.exports = { createBaseConfig };

package/webpack/config.dev.js

@@ -0,0 +1,23 @@
+const path = require('path');
+const ContentWatchPlugin = require('./content-watch-plugin');
+const { createBaseConfig } = require('./config.base');
+const { getDevSiteVariables } = require('./site-variables');
+const { getPackageDir } = require('./utils/paths');
+
+module.exports = async (env = {}) => {
+  const siteVariables = getDevSiteVariables();
+  const packageDir = getPackageDir();
+  const entry = { index: path.resolve(packageDir, 'src/index.ts') };
+  if (env.watchMode) {
+    entry.reload = path.resolve(packageDir, 'webpack/watch-reload-client.js');
+  }
+
+  return createBaseConfig({
+    mode: 'development',
+    devtool: 'inline-source-map',
+    siteVariables,
+    entry,
+    defineIsDev: true,
+    plugins: [new ContentWatchPlugin(siteVariables)],
+  });
+};

package/webpack/config.prod.js

@@ -0,0 +1,32 @@
+const path = require('path');
+const TerserPlugin = require('terser-webpack-plugin');
+const { createBaseConfig } = require('./config.base');
+const { compileTemplates } = require('./templates');
+const { getProdSiteVariables } = require('./site-variables');
+const { getPackageDir } = require('./utils/paths');
+
+const siteVariables = getProdSiteVariables();
+
+module.exports = async () => {
+  compileTemplates(siteVariables);
+
+  return createBaseConfig({
+    mode: 'production',
+    siteVariables,
+    entry: { index: path.resolve(getPackageDir(), 'src/index.ts') },
+    devtool: false,
+    optimization: {
+      minimizer: [
+        /*
+         * Bun's event loop doesn't track TerserPlugin's worker threads,
+         * causing a premature exit; set parallel to false to prevent worker
+         * threads from being used.
+         */
+        new TerserPlugin({
+          parallel: false,
+          terserOptions: { output: { comments: false } },
+        }),
+      ],
+    },
+  });
+};

package/webpack/content-watch-plugin.js

@@ -0,0 +1,153 @@
+const fs = require('fs');
+const path = require('path');
+const {
+  getContentDir,
+  getContentFiles,
+  getBuildContentFiles,
+} = require('./util');
+const { setWatchState } = require('./build-state');
+const {
+  compileTemplates,
+  getHtmlTemplatesDir,
+  getJsonDataDir,
+  JSON_DATA_FILES,
+} = require('./templates');
+const { getProjectDir } = require('./utils/paths');
+
+let _needsRestart = false;
+
+class ContentWatchPlugin {
+  constructor(siteVariables) {
+    this.siteVariables = siteVariables;
+    this.siteConfigPath = path.resolve(
+      getProjectDir(),
+      'config',
+      'site.dev.json',
+    );
+  }
+
+  apply(compiler) {
+    let lastSig = null;
+
+    compiler.hooks.make.tap('ContentWatchPlugin', compilation => {
+      const htmlTemplatesDir = getHtmlTemplatesDir();
+      const jsonDataDir = getJsonDataDir();
+
+      // Refresh templates cache from disk
+      try {
+        compileTemplates(this.siteVariables);
+      } catch (err) {
+        compilation.errors.push(err);
+        for (const fileName of fs.readdirSync(htmlTemplatesDir)) {
+          compilation.fileDependencies.add(
+            path.join(htmlTemplatesDir, fileName),
+          );
+        }
+        for (const dataFile of JSON_DATA_FILES) {
+          const dataPath = path.join(jsonDataDir, dataFile);
+          if (fs.existsSync(dataPath)) {
+            compilation.fileDependencies.add(dataPath);
+          }
+        }
+        return;
+      }
+
+      const contentDir = getContentDir();
+      const modifiedFiles = new Set(
+        [...(compiler.modifiedFiles || [])].map(filePath =>
+          path.resolve(filePath),
+        ),
+      );
+      const normalizedContentDir = path.resolve(contentDir) + path.sep;
+      const normalizedHtmlDir = path.resolve(htmlTemplatesDir) + path.sep;
+      const contentFiles = getContentFiles(
+        contentDir,
+        Object.keys(this.siteVariables.codeLanguages),
+      );
+      const buildContentFiles = getBuildContentFiles(
+        contentDir,
+        Object.keys(this.siteVariables.codeLanguages),
+      );
+
+      // Detect structural changes (files added or deleted) that require a
+      // fresh compiler with updated content asset caches
+      const sig = buildContentFiles.slice().sort().join('\0');
+      let structureChanged = false;
+      if (lastSig !== null && sig !== lastSig) {
+        _needsRestart = true;
+        structureChanged = true;
+      }
+      lastSig = sig;
+
+      const changedContentFiles = new Set(
+        [...modifiedFiles].filter(filePath =>
+          filePath.startsWith(normalizedContentDir),
+        ),
+      );
+
+      // Check if any HTML template or JSON data file changed
+      const jsonDataPaths = JSON_DATA_FILES.map(f =>
+        path.resolve(jsonDataDir, f),
+      );
+      const templatesChanged = [...modifiedFiles].some(
+        filePath =>
+          filePath === path.resolve(htmlTemplatesDir) ||
+          filePath.startsWith(normalizedHtmlDir) ||
+          jsonDataPaths.includes(filePath),
+      );
+
+      setWatchState(compiler, {
+        contentFiles,
+        buildContentFiles,
+        changedContentFiles,
+        templatesChanged,
+        structureChanged,
+      });
+
+      // Tell webpack to watch all content files
+      for (const filePath of contentFiles) {
+        compilation.fileDependencies.add(filePath);
+      }
+
+      // Watch content directories so webpack detects newly added files
+      function addDirs(dir) {
+        compilation.contextDependencies.add(dir);
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+          if (entry.isDirectory()) {
+            addDirs(path.join(dir, entry.name));
+          }
+        }
+      }
+      addDirs(contentDir);
+
+      // Watch HTML template files from the package
+      for (const fileName of fs.readdirSync(htmlTemplatesDir)) {
+        compilation.fileDependencies.add(path.join(htmlTemplatesDir, fileName));
+      }
+
+      // Watch JSON data files from the project config
+      for (const dataFile of JSON_DATA_FILES) {
+        const dataPath = path.join(jsonDataDir, dataFile);
+        if (fs.existsSync(dataPath)) {
+          compilation.fileDependencies.add(dataPath);
+        }
+      }
+
+      // Watch the site config file and restart when it changes
+      compilation.fileDependencies.add(this.siteConfigPath);
+      const siteConfigChanged = modifiedFiles.has(
+        path.resolve(this.siteConfigPath),
+      );
+      if (siteConfigChanged) {
+        _needsRestart = true;
+      }
+    });
+  }
+}
+
+ContentWatchPlugin.needsRestart = () => _needsRestart;
+ContentWatchPlugin.clearRestart = () => {
+  _needsRestart = false;
+};
+
+module.exports = ContentWatchPlugin;

package/webpack/deflist-id-plugin.js

@@ -0,0 +1,62 @@
+const textToId = require('./text-to-id');
+
+module.exports = function deflistIdPlugin(md) {
+  md.core.ruler.push('deflist_id_injector', function (state) {
+    const tokens = state.tokens;
+    const used = new Map();
+
+    function slugify(str) {
+      let slug = textToId(str);
+
+      if (!slug) {
+        slug = 'term';
+      }
+
+      if (used.has(slug)) {
+        const n = used.get(slug) + 1;
+        used.set(slug, n);
+        slug = `${slug}-${n}`;
+      } else {
+        used.set(slug, 1);
+      }
+
+      return slug;
+    }
+
+    for (let i = 0; i < tokens.length; i++) {
+      if (tokens[i].type !== 'dt_open') {
+        continue;
+      }
+
+      let termText = '';
+      for (let j = i + 1; j < tokens.length; j++) {
+        const t = tokens[j];
+
+        if (t.type === 'dt_close') {
+          break;
+        }
+
+        if (t.type === 'text') {
+          termText += t.content;
+        } else if (t.type === 'inline' && t.children) {
+          for (const child of t.children) {
+            if (child.type === 'text') {
+              termText += child.content;
+            }
+          }
+        }
+      }
+
+      if (!termText) {
+        continue;
+      }
+
+      const slug = slugify(termText);
+      const token = new state.Token('html_inline', '', 0);
+      token.content = `<a id="${slug}"></a>`;
+      tokens.splice(i + 1, 0, token);
+      // Skip token we just inserted
+      i++;
+    }
+  });
+};