@abreen/tada 1.0.2 → 1.1.0

package/{webpack/globals.js → build/globals.ts}

@@ -1,8 +1,23 @@
-const timezones = require('../src/timezone/timezones.json');
+import timezones from '../src/timezone/timezones.json' with { type: 'json' };
+import type { SiteVariables } from './types.js';
 
-module.exports = function createGlobals(site, page, subPath) {
-  const siteVars = page; // second arg receives siteVariables per render.js call convention
-  const defaultTz = timezones.find(t => t.value === siteVars.defaultTimeZone);
+interface Globals {
+  isHomePage: boolean;
+  isoDate: (str: string | null | undefined) => string | null;
+  readableDate: (date: string | Date | null | undefined) => string;
+  classNames: (obj: Record<string, unknown>) => string;
+  cx: (obj: Record<string, unknown>) => string;
+  timezoneChooser: string;
+}
+
+export default function createGlobals(
+  pageVariables: Record<string, unknown>,
+  siteVariables: SiteVariables,
+  subPath: string,
+): Globals {
+  const defaultTz = timezones.find(
+    t => t.value === siteVariables.defaultTimeZone,
+  );
   const timezoneChooser = defaultTz
     ? `<select class="time-zone" hidden></select><noscript>Times shown in ${defaultTz.abbreviation}.</noscript>`
     : '<select class="time-zone" hidden></select>';
@@ -15,9 +30,9 @@ module.exports = function createGlobals(site, page, subPath) {
     cx: classNames,
     timezoneChooser,
   };
-};
+}
 
-function isoDate(str) {
+function isoDate(str: string | null | undefined): string | null {
   if (str == null || str == '') {
     return null;
   }
@@ -25,7 +40,7 @@ function isoDate(str) {
   return date.toISOString().slice(0, 10);
 }
 
-function readableDate(date) {
+function readableDate(date: string | Date | null | undefined): string {
   if (date == null || date == '') {
     return '';
   }
@@ -36,16 +51,16 @@ function readableDate(date) {
 
   const str = date.toISOString();
   const year = str.slice(0, 4);
-  let month = str.slice(5, 7);
+  let month: string = str.slice(5, 7);
   if (month[0] === '0') {
     month = month[1];
   }
-  let day = str.slice(8, 10);
+  let day: string = str.slice(8, 10);
   if (day[0] === '0') {
     day = day[1];
   }
 
-  const months = {
+  const months: Record<string, string> = {
     1: 'January',
     2: 'February',
     3: 'March',
@@ -63,10 +78,10 @@ function readableDate(date) {
   return `${months[month]} ${day}, ${year}`;
 }
 
-function classNames(obj) {
-  const names = [];
+function classNames(obj: Record<string, unknown>): string {
+  const names: string[] = [];
   for (const key in obj) {
-    if (!!obj[key]) {
+    if (obj[key]) {
       names.push(key);
     }
   }

package/{webpack/heading-subtitle-plugin.js → build/heading-subtitle-plugin.ts}

@@ -1,4 +1,6 @@
-module.exports = function specialHeadingsPlugin(md) {
+import type MarkdownIt from 'markdown-it';
+
+export default function specialHeadingsPlugin(md: MarkdownIt): void {
   md.core.ruler.push('special_headings', state => {
     const tokens = state.tokens;
     for (let i = 0; i < tokens.length; i++) {
@@ -77,4 +79,4 @@ module.exports = function specialHeadingsPlugin(md) {
       tokens[i].attrJoin('class', 'has-subtitle');
     }
   });
-};
+}

package/build/json-schema.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, test } from 'bun:test';
+import { compile, doValidation } from './json-schema.js';
+
+const schema = {
+  type: 'object',
+  properties: { name: { type: 'string' }, age: { type: 'number' } },
+  required: ['name'],
+  additionalProperties: false,
+};
+
+describe('compile', () => {
+  test('returns a validate function', () => {
+    const validator = compile(schema);
+    expect(typeof validator).toBe('function');
+  });
+});
+
+describe('doValidation', () => {
+  test('does not throw for valid input', () => {
+    const validator = compile(schema);
+    expect(() =>
+      doValidation(validator, { name: 'Alice' }, 'test.json'),
+    ).not.toThrow();
+  });
+
+  test('does not throw when optional fields are present', () => {
+    const validator = compile(schema);
+    expect(() =>
+      doValidation(validator, { name: 'Alice', age: 30 }, 'test.json'),
+    ).not.toThrow();
+  });
+
+  test('throws when required field is missing', () => {
+    const validator = compile(schema);
+    expect(() => doValidation(validator, {}, 'test.json')).toThrow(
+      'test.json failed validation',
+    );
+  });
+
+  test('throws with additionalProperties message', () => {
+    const validator = compile(schema);
+    expect(() =>
+      doValidation(validator, { name: 'Alice', extra: true }, 'test.json'),
+    ).toThrow('unknown property "extra"');
+  });
+
+  test('throws with field path in error', () => {
+    const nestedSchema = {
+      type: 'object',
+      properties: { name: { type: 'string' } },
+    };
+    const validator = compile(nestedSchema);
+    expect(() => doValidation(validator, { name: 123 }, 'data.json')).toThrow(
+      'data.json failed validation',
+    );
+  });
+});

package/build/json-schema.ts

@@ -0,0 +1,33 @@
+import JsonSchemaCompiler from 'ajv';
+import type { ValidateFunction, ErrorObject } from 'ajv';
+
+const compiler = new JsonSchemaCompiler();
+
+export function compile(schema: object): ValidateFunction {
+  return compiler.compile(schema);
+}
+
+function formatValidationError(error: ErrorObject): string {
+  const path = error.instancePath || '/';
+  const parts: string[] = [path];
+  if (error.keyword === 'additionalProperties') {
+    parts.push(
+      `unknown property "${(error.params as { additionalProperty: string }).additionalProperty}"`,
+    );
+  } else {
+    parts.push(error.message || 'unknown error');
+  }
+  return parts.join(': ');
+}
+
+export function doValidation(
+  validator: ValidateFunction,
+  input: unknown,
+  fileName: string,
+): void {
+  const valid = validator(input);
+  if (!valid) {
+    const details = validator.errors!.map(formatValidationError).join('\n');
+    throw new Error(`${fileName} failed validation:\n${details}`);
+  }
+}

package/build/log.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, test } from 'bun:test';
+import { makeLogger, getFlair } from './log.js';
+
+function captureOutput(fn: () => void): { stdout: string; stderr: string } {
+  let stdout = '';
+  let stderr = '';
+  const origStdout = process.stdout.write;
+  const origStderr = process.stderr.write;
+  process.stdout.write = ((chunk: string) => {
+    stdout += chunk;
+    return true;
+  }) as typeof process.stdout.write;
+  process.stderr.write = ((chunk: string) => {
+    stderr += chunk;
+    return true;
+  }) as typeof process.stderr.write;
+  try {
+    fn();
+  } finally {
+    process.stdout.write = origStdout;
+    process.stderr.write = origStderr;
+  }
+  return { stdout, stderr };
+}
+
+describe('makeLogger', () => {
+  test('creates a logger with default info level', () => {
+    const log = makeLogger('test');
+    expect(log.minLogLevel).toBe('info');
+  });
+
+  test('throws on invalid log level', () => {
+    expect(() => makeLogger('test', 'verbose')).toThrow('Invalid log level');
+  });
+
+  test('info writes to stdout', () => {
+    const log = makeLogger('test', 'info');
+    const { stdout } = captureOutput(() => log.info`hello world`);
+    expect(stdout).toContain('hello world');
+  });
+
+  test('debug is suppressed at info level', () => {
+    const log = makeLogger('test', 'info');
+    const { stderr } = captureOutput(() => log.debug`should not appear`);
+    expect(stderr).toBe('');
+  });
+
+  test('debug appears at debug level', () => {
+    const log = makeLogger('test', 'debug');
+    const { stderr } = captureOutput(() => log.debug`visible`);
+    expect(stderr).toContain('visible');
+  });
+
+  test('warn writes to stdout', () => {
+    const log = makeLogger('test', 'warn');
+    const { stdout } = captureOutput(() => log.warn`caution`);
+    expect(stdout).toContain('caution');
+  });
+
+  test('error writes to stdout', () => {
+    const log = makeLogger('test', 'error');
+    const { stdout } = captureOutput(() => log.error`failure`);
+    expect(stdout).toContain('failure');
+  });
+
+  test('event always writes', () => {
+    const log = makeLogger('test', 'error');
+    const { stdout } = captureOutput(() => log.event`done`);
+    expect(stdout).toContain('done');
+  });
+
+  test('followup writes strings', () => {
+    const log = makeLogger('test');
+    const { stdout } = captureOutput(() => log.followup(['line1', 'line2']));
+    expect(stdout).toContain('line1');
+    expect(stdout).toContain('line2');
+  });
+
+  test('setMinLogLevel changes filtering', () => {
+    const log = makeLogger('test', 'info');
+    log.setMinLogLevel('error');
+    const { stdout } = captureOutput(() => log.info`suppressed`);
+    expect(stdout).toBe('');
+  });
+
+  test('handles empty name', () => {
+    const log = makeLogger('');
+    expect(log.minLogLevel).toBe('info');
+  });
+
+  test('handles __filename-style name', () => {
+    const log = makeLogger('/path/to/module.ts');
+    const { stdout } = captureOutput(() => log.info`test`);
+    expect(stdout).toContain('test');
+  });
+
+  test('interpolates objects in template', () => {
+    const log = makeLogger('test');
+    const obj = { key: 'value' };
+    const { stdout } = captureOutput(() => log.info`data: ${obj}`);
+    expect(stdout).toContain('key');
+  });
+});
+
+describe('getFlair', () => {
+  test('returns a non-empty string with emoji', () => {
+    const flair = getFlair();
+    expect(flair.length).toBeGreaterThan(0);
+    expect(flair).toContain('🎉');
+  });
+});

package/build/log.ts

@@ -0,0 +1,167 @@
+import { inspect } from 'node:util';
+import path from 'path';
+import { Gi, L, Ri, P, Yi, Li } from './colors.js';
+import type { Logger } from './types.js';
+import FLAIR_STRINGS from './flair.json' with { type: 'json' };
+
+const LEVELS = ['debug', 'info', 'warn', 'error'] as const;
+
+type LogLevel = (typeof LEVELS)[number];
+
+const ENV_LOG_LEVEL = process.env.TADA_LOG_LEVEL;
+
+if (ENV_LOG_LEVEL && !LEVELS.includes(ENV_LOG_LEVEL as LogLevel)) {
+  throw new Error(
+    `Invalid TADA_LOG_LEVEL "${ENV_LOG_LEVEL}", must be one of: ${LEVELS.join(', ')}`,
+  );
+}
+
+function shouldLog(loggerLevel: string, level: string): boolean {
+  return (
+    LEVELS.indexOf(level as LogLevel) >= LEVELS.indexOf(loggerLevel as LogLevel)
+  );
+}
+
+function validateLevel(level: string): void {
+  if (!LEVELS.includes(level as LogLevel)) {
+    throw new Error(
+      `Invalid log level "${level}", must be one of: ${LEVELS.join(', ')}`,
+    );
+  }
+}
+
+function print(
+  strings: string[],
+  stream: 'stdout' | 'stderr' = 'stdout',
+  end: string = '\n',
+): void {
+  for (const s of strings) {
+    process[stream].write(s);
+  }
+  process[stream].write(end);
+}
+
+export function makeLogger(name: string, logLevel: string = 'info'): Logger {
+  validateLevel(logLevel);
+
+  if (ENV_LOG_LEVEL) {
+    logLevel = ENV_LOG_LEVEL;
+  }
+
+  if (!name) {
+    name = '';
+  } else {
+    // Allow for passing __filename
+    name = path.basename(name, path.extname(name));
+  }
+
+  const logger: Logger = {
+    minLogLevel: logLevel,
+    /** Don't log if the level is < minLogLevel */
+    setMinLogLevel(minLogLevel: string) {
+      this.minLogLevel = minLogLevel;
+    },
+    getArgs(
+      level: string,
+      strings: TemplateStringsArray | string | string[],
+      args: unknown[],
+      labelFn: (strings: TemplateStringsArray, ...args: unknown[]) => string,
+    ): string[] {
+      const params: string[] = [];
+      params.push(
+        labelFn` ${level} ` + ' ' + (level === 'debug' ? name + ' ' : ''),
+      );
+      params.push(format(strings, ...args));
+      return params;
+    },
+    debug(strings: TemplateStringsArray, ...args: unknown[]) {
+      if (shouldLog(this.minLogLevel, 'debug')) {
+        print(this.getArgs('debug', strings, args, L), 'stderr');
+      }
+    },
+    info(strings: TemplateStringsArray, ...args: unknown[]) {
+      if (shouldLog(this.minLogLevel, 'info')) {
+        print(this.getArgs('info', strings, args, Li));
+      }
+    },
+    warn(strings: TemplateStringsArray, ...args: unknown[]) {
+      if (shouldLog(this.minLogLevel, 'warn')) {
+        print(this.getArgs('warn', strings, args, Yi));
+      }
+    },
+    error(strings: TemplateStringsArray, ...args: unknown[]) {
+      if (shouldLog(this.minLogLevel, 'error')) {
+        print(this.getArgs('error', strings, args, Ri));
+      }
+    },
+    event(strings: TemplateStringsArray, ...args: unknown[]) {
+      print(this.getArgs('event', strings, args, Gi));
+    },
+    followup(strings: string[]) {
+      print(strings);
+    },
+  };
+
+  logger.setMinLogLevel(logLevel);
+  return logger;
+}
+
+function format(
+  strings: TemplateStringsArray | string | string[],
+  ...args: unknown[]
+): string {
+  // Called as template tag: first arg is an array-like with .raw
+  if (strings && typeof strings === 'object' && 'raw' in strings) {
+    try {
+      return String.raw(strings as TemplateStringsArray, ...args.map(toString));
+    } catch {
+      // fallback to safe join
+    }
+  } else {
+    if (Array.isArray(strings)) {
+      args.unshift(...strings);
+    } else {
+      args.unshift(strings);
+    }
+
+    return args.map(toString).join(' ');
+  }
+
+  return '';
+}
+
+function toString(item: unknown): string {
+  if (item === undefined) {
+    return 'undefined';
+  }
+  if (item === null) {
+    return 'null';
+  }
+  if (typeof item === 'string') {
+    return item;
+  }
+
+  try {
+    if (typeof item === 'object') {
+      return inspect(item, {
+        compact: true,
+        depth: 2,
+        breakLength: 80,
+        maxStringLength: 250,
+        colors: true,
+      });
+    }
+    throw new Error('not an object');
+  } catch {
+    return String(item);
+  }
+}
+
+export function getFlair(): string {
+  const i = Math.floor(Math.random() * FLAIR_STRINGS.length);
+  return P`${FLAIR_STRINGS[i]}!` + ' 🎉';
+}
+
+export function printFlair(): void {
+  console.log(getFlair());
+}

package/{webpack/markdown-plugins.test.js → build/markdown-plugins.test.ts}

@@ -1,11 +1,13 @@
-const { describe, expect, test } = require('bun:test');
-const MarkdownIt = require('markdown-it');
-const deflist = require('markdown-it-deflist');
-const applyBasePathPlugin = require('./apply-base-path-plugin');
-const deflistIdPlugin = require('./deflist-id-plugin');
-const externalLinksPlugin = require('./external-links-plugin');
-const headingSubtitlePlugin = require('./heading-subtitle-plugin');
-const { createMarkdown } = require('./utils/markdown');
+import { describe, expect, test } from 'bun:test';
+import MarkdownIt from 'markdown-it';
+import deflist from 'markdown-it-deflist';
+import applyBasePathPlugin from './apply-base-path-plugin.js';
+import deflistIdPlugin from './deflist-id-plugin.js';
+import externalLinksPlugin from './external-links-plugin.js';
+import headingSubtitlePlugin from './heading-subtitle-plugin.js';
+import { createMarkdown } from './utils/markdown.js';
+import { stripHtmlComments } from './utils/render.js';
+import type { SiteVariables } from './types.js';
 
 describe('apply-base-path-plugin', () => {
   test('rewrites internal links, images, and raw html image sources', () => {
@@ -115,7 +117,13 @@ describe('deflist-id-plugin', () => {
 describe('custom markdown containers', () => {
   function createProjectMarkdown() {
     return createMarkdown(
-      { basePath: '/', internalDomains: [], codeLanguages: {}, features: {} },
+      {
+        base: '',
+        basePath: '/',
+        internalDomains: [],
+        codeLanguages: {},
+        features: {},
+      } as SiteVariables,
       { validatorOptions: { enabled: false } },
     );
   }
@@ -201,3 +209,80 @@ describe('custom markdown containers', () => {
     expect(html).toContain('<p>Careful</p>');
   });
 });
+
+describe('hidden_fence rule', () => {
+  function createProjectMarkdown() {
+    return createMarkdown(
+      {
+        base: '',
+        basePath: '/',
+        internalDomains: [],
+        codeLanguages: {},
+        features: {},
+      } as SiteVariables,
+      { validatorOptions: { enabled: false } },
+    );
+  }
+
+  test('removes triple-hyphen comments containing a code fence', () => {
+    const md = createProjectMarkdown();
+
+    const html = md.render(
+      ['<!---', '```', 'import java.util.*;', '```', '-->'].join('\n'),
+    );
+
+    expect(html).not.toContain('<!---');
+    expect(html).not.toContain('import java.util');
+  });
+
+  test('does not remove triple-hyphen comments without a code fence', () => {
+    const md = createProjectMarkdown();
+
+    const html = md.render(
+      ['<!---', 'This is a plain comment.', '-->'].join('\n'),
+    );
+
+    // markdown-it passes through html_block tokens unchanged;
+    // the hidden_fence rule only converts comments that contain fences
+    expect(html).toContain('<!---');
+  });
+
+  test('preserves double-hyphen HTML comments', () => {
+    const md = createProjectMarkdown();
+
+    const html = md.render(['<!-- standard HTML comment -->'].join('\n'));
+
+    expect(html).toContain('<!-- standard HTML comment -->');
+  });
+});
+
+describe('stripHtmlComments', () => {
+  test('removes a single triple-hyphen comment', () => {
+    const result = stripHtmlComments(
+      '<p>Before</p>\n<!--- hidden comment -->\n<p>After</p>',
+    );
+    expect(result).toBe('<p>Before</p>\n\n<p>After</p>');
+  });
+
+  test('removes multiple triple-hyphen comments', () => {
+    const result = stripHtmlComments('<!--- first -->\ntext\n<!--- second -->');
+    expect(result).toBe('\ntext\n');
+  });
+
+  test('removes triple-hyphen comments spanning multiple lines', () => {
+    const result = stripHtmlComments(
+      '<p>Keep</p>\n<!---\nLine 1\nLine 2\n-->\n<p>Also keep</p>',
+    );
+    expect(result).toBe('<p>Keep</p>\n\n<p>Also keep</p>');
+  });
+
+  test('does not remove double-hyphen HTML comments', () => {
+    const input = '<p>Before</p>\n<!-- keep this -->\n<p>After</p>';
+    expect(stripHtmlComments(input)).toBe(input);
+  });
+
+  test('returns input unchanged when there are no comments', () => {
+    const input = '<p>Hello world</p>';
+    expect(stripHtmlComments(input)).toBe(input);
+  });
+});