@abreen/tada 1.0.2 → 1.1.0

package/build/toc-plugin.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, test } from 'bun:test';
+import { generateTocHtml, generateCodeTocHtml } from './toc-plugin.js';
+import type { JavaTocEntry } from './types.js';
+
+describe('generateTocHtml', () => {
+  test('returns empty string for empty array', () => {
+    expect(generateTocHtml([])).toBe('');
+  });
+
+  test('returns empty string for null/undefined', () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect(generateTocHtml(null as any)).toBe('');
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect(generateTocHtml(undefined as any)).toBe('');
+  });
+
+  test('generates heading items with correct level and link', () => {
+    const html = generateTocHtml([
+      { kind: 'heading', level: '2', id: 'intro', innerHtml: 'Introduction' },
+    ]);
+    expect(html).toContain('<ol>');
+    expect(html).toContain('class="heading-item level2"');
+    expect(html).toContain('href="#intro"');
+    expect(html).toContain('Introduction');
+    expect(html).toContain('</ol>');
+  });
+
+  test('generates dinkus items', () => {
+    const html = generateTocHtml([{ kind: 'dinkus' }]);
+    expect(html).toContain('class="dinkus-item"');
+  });
+
+  test('generates alert items at one level deeper than last heading', () => {
+    const html = generateTocHtml([
+      { kind: 'heading', level: '2', id: 'sec', innerHtml: 'Section' },
+      { kind: 'alert', type: 'warning', title: 'Caution' },
+    ]);
+    expect(html).toContain('class="alert-item level3 warning"');
+    expect(html).toContain('Caution');
+  });
+
+  test('alert before any heading uses level 2 (lastHeadingLevel defaults to 1)', () => {
+    const html = generateTocHtml([
+      { kind: 'alert', type: 'note', title: 'Note' },
+    ]);
+    expect(html).toContain('class="alert-item level2 note"');
+  });
+
+  test('handles mixed items in order', () => {
+    const html = generateTocHtml([
+      { kind: 'heading', level: '2', id: 'a', innerHtml: 'A' },
+      { kind: 'dinkus' },
+      { kind: 'heading', level: '3', id: 'b', innerHtml: 'B' },
+      { kind: 'alert', type: 'note', title: 'FYI' },
+    ]);
+    expect(html).toContain('level2');
+    expect(html).toContain('dinkus-item');
+    expect(html).toContain('level3');
+    expect(html).toContain('level4');
+  });
+});
+
+describe('generateCodeTocHtml', () => {
+  test('returns empty string for empty array', () => {
+    expect(generateCodeTocHtml([])).toBe('');
+  });
+
+  test('returns empty string for null/undefined', () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect(generateCodeTocHtml(null as any)).toBe('');
+  });
+
+  test('generates grouped entries with labels', () => {
+    const items: JavaTocEntry[] = [
+      { kind: 'field', label: 'x', name: 'x', line: 5 },
+      { kind: 'method', label: 'getX()', name: 'getX()', line: 10 },
+    ];
+    const html = generateCodeTocHtml(items);
+    expect(html).toContain('Fields');
+    expect(html).toContain('Methods');
+    expect(html).toContain('href="#L5"');
+    expect(html).toContain('href="#L10"');
+  });
+
+  test('groups items by kind in order of appearance', () => {
+    const items: JavaTocEntry[] = [
+      { kind: 'method', label: 'foo()', name: 'foo()', line: 1 },
+      { kind: 'constructor', label: 'Bar()', name: 'Bar()', line: 5 },
+      { kind: 'method', label: 'baz()', name: 'baz()', line: 10 },
+    ];
+    const html = generateCodeTocHtml(items);
+    const methodsPos = html.indexOf('Methods');
+    const constructorsPos = html.indexOf('Constructors');
+    expect(methodsPos).toBeLessThan(constructorsPos);
+  });
+
+  test('escapes HTML in names', () => {
+    const items: JavaTocEntry[] = [
+      { kind: 'method', label: 'compare<T>()', name: 'compare<T>()', line: 1 },
+    ];
+    const html = generateCodeTocHtml(items);
+    expect(html).toContain('compare&lt;T&gt;()');
+    expect(html).not.toContain('compare<T>()');
+  });
+});

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

@@ -1,14 +1,35 @@
-const { convertMarkdown: curlyQuote } = require('quote-quote');
+import type MarkdownIt from 'markdown-it';
+import { convertMarkdown as curlyQuote } from 'quote-quote';
+import type { JavaTocEntry } from './types.js';
+
+interface HeadingItem {
+  kind: 'heading';
+  level: string;
+  id: string;
+  innerHtml: string;
+}
+
+interface DinkusItem {
+  kind: 'dinkus';
+}
 
-function tocPlugin(md) {
+interface AlertItem {
+  kind: 'alert';
+  type: string;
+  title: string;
+}
+
+type TocItem = HeadingItem | DinkusItem | AlertItem;
+
+export function tocPlugin(md: MarkdownIt): void {
   md.core.ruler.push('toc_collector', state => {
     if (!state.env) {
       return;
     }
 
     const tokens = state.tokens;
-    const items = [];
-    const containerStack = [];
+    const items: TocItem[] = [];
+    const containerStack: string[] = [];
 
     for (let i = 0; i < tokens.length; i++) {
       const token = tokens[i];
@@ -23,7 +44,7 @@ function tocPlugin(md) {
         const level = token.tag[1]; // 'h2' -> '2'
         const id = token.attrGet('id') || '';
         const innerHtml = md.renderer.renderInline(
-          inline.children,
+          inline.children ?? [],
           md.options,
           state.env,
         );
@@ -82,7 +103,7 @@ function tocPlugin(md) {
   });
 }
 
-function generateTocHtml(tocItems) {
+export function generateTocHtml(tocItems: TocItem[]): string {
   if (!tocItems || tocItems.length === 0) {
     return '';
   }
@@ -118,7 +139,7 @@ function generateTocHtml(tocItems) {
   return parts.join('');
 }
 
-function escapeHtml(str) {
+function escapeHtml(str: string): string {
   return str
     .replace(/&/g, '&amp;')
     .replace(/</g, '&lt;')
@@ -126,19 +147,19 @@ function escapeHtml(str) {
     .replace(/"/g, '&quot;');
 }
 
-const GROUP_LABELS = {
+const GROUP_LABELS: Record<string, string> = {
   field: 'Fields',
   constructor: 'Constructors',
   method: 'Methods',
 };
 
-function generateCodeTocHtml(codeTocItems) {
+export function generateCodeTocHtml(codeTocItems: JavaTocEntry[]): string {
   if (!codeTocItems || codeTocItems.length === 0) {
     return '';
   }
 
-  const groups = Object.create(null);
-  const kindOrder = [];
+  const groups: Record<string, JavaTocEntry[]> = Object.create(null);
+  const kindOrder: string[] = [];
   for (const item of codeTocItems) {
     if (!groups[item.kind]) {
       groups[item.kind] = [];
@@ -163,5 +184,3 @@ function generateCodeTocHtml(codeTocItems) {
   parts.push('</ol>');
   return parts.join('');
 }
-
-module.exports = { tocPlugin, generateTocHtml, generateCodeTocHtml };

package/build/types.ts

@@ -0,0 +1,172 @@
+/** Site configuration loaded from site.dev.json or site.prod.json */
+export interface SiteVariables {
+  base: string;
+  basePath: string;
+  title?: string;
+  titlePostfix?: string;
+  symbol?: string;
+  faviconSymbol?: string;
+  courseId?: string;
+  themeColor?: string;
+  faviconColor?: string;
+  faviconFontWeight?: number;
+  internalDomains?: string[];
+  defaultTimeZone?: string;
+  features?: { search?: boolean; code?: boolean; favicon?: boolean };
+  codeLanguages?: Record<string, string>;
+  tintHue?: number;
+  tintAmount?: number;
+  vars?: Record<string, unknown>;
+}
+
+/** A rendered content asset ready to write to dist/ */
+export interface Asset {
+  assetPath: string;
+  content: string | Buffer;
+}
+
+/** Options for the content rendering pipeline */
+export interface ContentRenderOptions {
+  distDir: string;
+  assetFiles: string[];
+  watchState?: WatchState;
+}
+
+/** State passed from watch mode to control incremental rebuilds */
+export interface WatchState {
+  changedContentFiles?: Set<string>;
+  templatesChanged?: boolean;
+}
+
+/** Result from ContentRenderer.processContent() */
+export interface ContentRenderResult {
+  errors: Error[];
+  changedHtmlAssetPaths: Set<string>;
+  removedHtmlAssetPaths: Set<string>;
+  htmlAssetsByPath: Map<string, string>;
+  buildContentFiles: string[];
+}
+
+/** Logger returned by makeLogger() */
+export interface Logger {
+  minLogLevel: string;
+  setMinLogLevel(level: string): void;
+  getArgs(
+    level: string,
+    strings: TemplateStringsArray | string | string[],
+    args: unknown[],
+    colorFn: (strings: TemplateStringsArray, ...args: unknown[]) => string,
+  ): string[];
+  debug(strings: TemplateStringsArray, ...args: unknown[]): void;
+  info(strings: TemplateStringsArray, ...args: unknown[]): void;
+  warn(strings: TemplateStringsArray, ...args: unknown[]): void;
+  error(strings: TemplateStringsArray, ...args: unknown[]): void;
+  event(strings: TemplateStringsArray, ...args: unknown[]): void;
+  followup(strings: string[]): void;
+}
+
+/** Options for plain text asset rendering */
+export interface RenderPlainTextOptions {
+  filePath: string;
+  contentDir: string;
+  siteVariables: SiteVariables;
+  validInternalTargets: Set<string>;
+  assetFiles: string[];
+}
+
+/** Options for code page asset rendering */
+export interface RenderCodePageOptions {
+  filePath: string;
+  contentDir: string;
+  siteVariables: SiteVariables;
+  assetFiles: string[];
+}
+
+/** Options for literate Java asset rendering */
+export interface RenderLiterateJavaOptions {
+  filePath: string;
+  contentDir: string;
+  siteVariables: SiteVariables;
+  assetFiles: string[];
+  skipExecution?: boolean;
+}
+
+/** Options for copied content asset rendering */
+export interface RenderCopiedContentOptions {
+  filePath: string;
+  contentDir: string;
+}
+
+/** Front matter parse result (from parseFrontMatterAndContent) */
+export interface ParsedContent {
+  pageVariables: Record<string, unknown>;
+  content: string;
+}
+
+/** Front matter parse result (from parseFrontMatter) */
+export interface ParsedFrontMatter {
+  frontMatter: Record<string, unknown>;
+  content: string;
+}
+
+/** Theme derivation result */
+export interface DerivedTheme {
+  themeColorLight: string;
+  themeColorDark: string;
+  themeColorTextLight: string;
+  themeColorTextDark: string;
+  textOnThemeLight: string;
+  textOnThemeDark: string;
+}
+
+/** Java code TOC entry from extractJavaMethodToc */
+export interface JavaTocEntry {
+  kind: 'method' | 'constructor' | 'field';
+  label: string;
+  name: string;
+  line: number;
+}
+
+/** Heading TOC item collected by toc-plugin */
+export interface HeadingTocItem {
+  id: string;
+  text: string;
+  level: number;
+  subtitle?: string;
+}
+
+/** Literate Java code block */
+export interface LiterateCodeBlock {
+  javaStartLine: number;
+  javaEndLine: number;
+  content: string;
+  hidden: boolean;
+}
+
+/** Result from parseLiterateJava */
+export interface LiterateJavaParseResult {
+  pageVariables: Record<string, unknown>;
+  content: string;
+  javaSource: string;
+  codeBlocks: LiterateCodeBlock[];
+  visibleBlockIndices: number[];
+}
+
+/** Execution output entry from LiterateRunner */
+export interface LiterateRunnerEntry {
+  blockIndex: number;
+  output: string;
+}
+
+/** Site config creation input (used by bin/validators) */
+export interface SiteConfigInput {
+  title: string;
+  symbol: string;
+  themeColor: string;
+  tintHue: string;
+  tintAmount: string;
+  defaultTimeZone: string;
+  base: string;
+  basePath: string;
+  internalDomains: string[];
+}

package/build/util.ts

@@ -0,0 +1,26 @@
+export {
+  getBuildContentFiles,
+  getContentFiles,
+  getFilesByExtensions,
+  getValidInternalTargets,
+  shouldSkipContentFile,
+} from './utils/content-files.js';
+export { extensionIsMarkdown } from './utils/file-types.js';
+export { createMarkdown } from './utils/markdown.js';
+export {
+  createApplyBasePath,
+  getContentDir,
+  getDistDir,
+  getPackageDir,
+  getProjectDir,
+  getPublicDir,
+  normalizeOutputPath,
+} from './utils/paths.js';
+export {
+  injectAssetTags,
+  renderCodePageAsset,
+  renderCopiedContentAsset,
+  renderLiterateJavaPageAsset,
+  renderPlainTextPageAsset,
+} from './utils/render.js';
+export { parseFrontMatter } from './utils/front-matter.js';