eprec 0.0.1 → 1.1.0

package/process-course/utils/chapter-selection.test.ts

@@ -0,0 +1,307 @@
+import { test, expect } from 'bun:test'
+import {
+	parseChapterSelection,
+	resolveChapterSelection,
+} from './chapter-selection'
+import type { ChapterSelection } from '../types'
+
+// Factory for creating expected selection results
+function createSelection(
+	base: 0 | 1,
+	...ranges: Array<[number, number | null]>
+): ChapterSelection {
+	return {
+		base,
+		ranges: ranges.map(([start, end]) => ({ start, end })),
+	}
+}
+
+// parseChapterSelection - single values
+test('parseChapterSelection parses single string number', () => {
+	expect(parseChapterSelection('4')).toEqual(createSelection(1, [4, 4]))
+})
+
+test('parseChapterSelection parses numeric input', () => {
+	expect(parseChapterSelection(4)).toEqual(createSelection(1, [4, 4]))
+})
+
+test('parseChapterSelection parses zero as base-0', () => {
+	expect(parseChapterSelection('0')).toEqual(createSelection(0, [0, 0]))
+})
+
+test('parseChapterSelection parses zero numeric as base-0', () => {
+	expect(parseChapterSelection(0)).toEqual(createSelection(0, [0, 0]))
+})
+
+// parseChapterSelection - ranges
+test('parseChapterSelection parses simple range', () => {
+	expect(parseChapterSelection('4-6')).toEqual(createSelection(1, [4, 6]))
+})
+
+test('parseChapterSelection parses range with spaces', () => {
+	expect(parseChapterSelection('4 - 6')).toEqual(createSelection(1, [4, 6]))
+})
+
+test('parseChapterSelection parses open-ended wildcard range', () => {
+	expect(parseChapterSelection('4-*')).toEqual(createSelection(1, [4, null]))
+})
+
+test('parseChapterSelection parses range starting at zero as base-0', () => {
+	expect(parseChapterSelection('0-5')).toEqual(createSelection(0, [0, 5]))
+})
+
+test('parseChapterSelection parses zero-to-zero range', () => {
+	expect(parseChapterSelection('0-0')).toEqual(createSelection(0, [0, 0]))
+})
+
+// parseChapterSelection - comma-separated
+test('parseChapterSelection parses comma-separated values', () => {
+	expect(parseChapterSelection('4,6,9')).toEqual(
+		createSelection(1, [4, 4], [6, 6], [9, 9]),
+	)
+})
+
+test('parseChapterSelection parses comma-separated with spaces', () => {
+	expect(parseChapterSelection('4, 6, 9')).toEqual(
+		createSelection(1, [4, 4], [6, 6], [9, 9]),
+	)
+})
+
+test('parseChapterSelection parses mixed values and ranges', () => {
+	expect(parseChapterSelection('4,6,9-12')).toEqual(
+		createSelection(1, [4, 4], [6, 6], [9, 12]),
+	)
+})
+
+test('parseChapterSelection parses complex selection with wildcard', () => {
+	expect(parseChapterSelection('1,3-5,8-*')).toEqual(
+		createSelection(1, [1, 1], [3, 5], [8, null]),
+	)
+})
+
+// parseChapterSelection - array input
+test('parseChapterSelection parses array of numbers', () => {
+	expect(parseChapterSelection([4, 6, 9])).toEqual(
+		createSelection(1, [4, 4], [6, 6], [9, 9]),
+	)
+})
+
+test('parseChapterSelection parses array of strings', () => {
+	expect(parseChapterSelection(['4', '6-8'])).toEqual(
+		createSelection(1, [4, 4], [6, 8]),
+	)
+})
+
+test('parseChapterSelection parses mixed array', () => {
+	expect(parseChapterSelection([4, '6-8', 10])).toEqual(
+		createSelection(1, [4, 4], [6, 8], [10, 10]),
+	)
+})
+
+test('parseChapterSelection skips null and undefined in array', () => {
+	expect(parseChapterSelection([4, null, 6, undefined, 8])).toEqual(
+		createSelection(1, [4, 4], [6, 6], [8, 8]),
+	)
+})
+
+test('parseChapterSelection skips empty strings in array', () => {
+	expect(parseChapterSelection(['4', '', '6'])).toEqual(
+		createSelection(1, [4, 4], [6, 6]),
+	)
+})
+
+// parseChapterSelection - edge cases
+test('parseChapterSelection trims whitespace', () => {
+	expect(parseChapterSelection('  4  ')).toEqual(createSelection(1, [4, 4]))
+})
+
+test('parseChapterSelection handles mixed zero and non-zero as base-0', () => {
+	expect(parseChapterSelection('0,5')).toEqual(
+		createSelection(0, [0, 0], [5, 5]),
+	)
+})
+
+// parseChapterSelection - error cases
+test('parseChapterSelection throws for empty string', () => {
+	expect(() => parseChapterSelection('')).toThrow(
+		'chapter must include at least one value',
+	)
+})
+
+test('parseChapterSelection throws for whitespace-only', () => {
+	expect(() => parseChapterSelection('   ')).toThrow(
+		'chapter must include at least one value',
+	)
+})
+
+test('parseChapterSelection throws for empty array', () => {
+	expect(() => parseChapterSelection([])).toThrow(
+		'chapter must include at least one value',
+	)
+})
+
+test('parseChapterSelection throws for array of nulls', () => {
+	expect(() => parseChapterSelection([null, null])).toThrow(
+		'chapter must include at least one value',
+	)
+})
+
+test('parseChapterSelection throws for invalid string', () => {
+	expect(() => parseChapterSelection('abc')).toThrow(
+		'Invalid chapter value: "abc"',
+	)
+})
+
+test('parseChapterSelection throws for negative value', () => {
+	expect(() => parseChapterSelection('-5')).toThrow(
+		'Invalid chapter value: "-5"',
+	)
+})
+
+test('parseChapterSelection throws for reversed range', () => {
+	expect(() => parseChapterSelection('10-5')).toThrow(
+		'chapter ranges must be low-to-high: "10-5"',
+	)
+})
+
+test('parseChapterSelection throws for object input', () => {
+	expect(() => parseChapterSelection({ value: 5 })).toThrow(
+		'chapter must be a number or range',
+	)
+})
+
+test('parseChapterSelection throws for boolean input', () => {
+	expect(() => parseChapterSelection(true)).toThrow(
+		'chapter must be a number or range',
+	)
+})
+
+// resolveChapterSelection - 1-based
+test('resolveChapterSelection resolves single 1-based chapter to index', () => {
+	const selection = parseChapterSelection('4')
+	expect(resolveChapterSelection(selection, 10)).toEqual([3])
+})
+
+test('resolveChapterSelection resolves 1-based range to indexes', () => {
+	const selection = parseChapterSelection('4-6')
+	expect(resolveChapterSelection(selection, 10)).toEqual([3, 4, 5])
+})
+
+test('resolveChapterSelection resolves open-ended range to end', () => {
+	const selection = parseChapterSelection('8-*')
+	expect(resolveChapterSelection(selection, 10)).toEqual([7, 8, 9])
+})
+
+test('resolveChapterSelection resolves comma-separated to indexes', () => {
+	const selection = parseChapterSelection('2,5,8')
+	expect(resolveChapterSelection(selection, 10)).toEqual([1, 4, 7])
+})
+
+test('resolveChapterSelection resolves complex selection', () => {
+	const selection = parseChapterSelection('1,3-5,9')
+	expect(resolveChapterSelection(selection, 10)).toEqual([0, 2, 3, 4, 8])
+})
+
+test('resolveChapterSelection deduplicates overlapping ranges', () => {
+	const selection = parseChapterSelection('3-5,4-6')
+	expect(resolveChapterSelection(selection, 10)).toEqual([2, 3, 4, 5])
+})
+
+test('resolveChapterSelection sorts results', () => {
+	const selection = parseChapterSelection('8,2,5')
+	expect(resolveChapterSelection(selection, 10)).toEqual([1, 4, 7])
+})
+
+// resolveChapterSelection - 0-based
+test('resolveChapterSelection resolves 0-based single chapter', () => {
+	const selection = parseChapterSelection('0')
+	expect(resolveChapterSelection(selection, 10)).toEqual([0])
+})
+
+test('resolveChapterSelection resolves 0-based range', () => {
+	const selection = parseChapterSelection('0-3')
+	expect(resolveChapterSelection(selection, 10)).toEqual([0, 1, 2, 3])
+})
+
+test('resolveChapterSelection resolves 0-based open-ended range', () => {
+	const selection = parseChapterSelection('0-*')
+	expect(resolveChapterSelection(selection, 10)).toEqual([
+		0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
+	])
+})
+
+test('resolveChapterSelection resolves 0-based mixed values', () => {
+	const selection = parseChapterSelection('0,5,9')
+	expect(resolveChapterSelection(selection, 10)).toEqual([0, 5, 9])
+})
+
+// resolveChapterSelection - boundary cases
+test('resolveChapterSelection resolves first chapter (1-based)', () => {
+	const selection = parseChapterSelection('1')
+	expect(resolveChapterSelection(selection, 5)).toEqual([0])
+})
+
+test('resolveChapterSelection resolves last chapter (1-based)', () => {
+	const selection = parseChapterSelection('5')
+	expect(resolveChapterSelection(selection, 5)).toEqual([4])
+})
+
+test('resolveChapterSelection resolves all chapters with 1-*', () => {
+	const selection = parseChapterSelection('1-*')
+	expect(resolveChapterSelection(selection, 5)).toEqual([0, 1, 2, 3, 4])
+})
+
+test('resolveChapterSelection handles single chapter count', () => {
+	const selection = parseChapterSelection('1')
+	expect(resolveChapterSelection(selection, 1)).toEqual([0])
+})
+
+// resolveChapterSelection - error cases
+test('resolveChapterSelection throws for zero chapter count', () => {
+	const selection = parseChapterSelection('1')
+	expect(() => resolveChapterSelection(selection, 0)).toThrow(
+		'Chapter count must be a positive number',
+	)
+})
+
+test('resolveChapterSelection throws for negative chapter count', () => {
+	const selection = parseChapterSelection('1')
+	expect(() => resolveChapterSelection(selection, -5)).toThrow(
+		'Chapter count must be a positive number',
+	)
+})
+
+test('resolveChapterSelection throws for NaN chapter count', () => {
+	const selection = parseChapterSelection('1')
+	expect(() => resolveChapterSelection(selection, NaN)).toThrow(
+		'Chapter count must be a positive number',
+	)
+})
+
+test('resolveChapterSelection throws for chapter beyond count', () => {
+	const selection = parseChapterSelection('15')
+	expect(() => resolveChapterSelection(selection, 10)).toThrow(
+		'chapter range starts at 15, but only 10 chapters exist',
+	)
+})
+
+test('resolveChapterSelection throws for range starting beyond count', () => {
+	const selection = parseChapterSelection('12-15')
+	expect(() => resolveChapterSelection(selection, 10)).toThrow(
+		'chapter range starts at 12, but only 10 chapters exist',
+	)
+})
+
+test('resolveChapterSelection throws for range ending beyond count', () => {
+	const selection = parseChapterSelection('8-15')
+	expect(() => resolveChapterSelection(selection, 10)).toThrow(
+		'chapter range ends at 15, but only 10 chapters exist',
+	)
+})
+
+test('resolveChapterSelection throws for 0-based chapter beyond count', () => {
+	const selection = parseChapterSelection('0,10')
+	expect(() => resolveChapterSelection(selection, 10)).toThrow(
+		'chapter range starts at 10, but only 10 chapters exist',
+	)
+})

package/process-course/utils/chapter-selection.ts

@@ -0,0 +1,136 @@
+import type { ChapterRange, ChapterSelection } from '../types'
+
+/**
+ * Parse a chapter selection string (e.g., "4", "4-6", "4,6,9-12", "4-*").
+ */
+export function parseChapterSelection(rawSelection: unknown): ChapterSelection {
+	const rawList = Array.isArray(rawSelection) ? rawSelection : [rawSelection]
+	const parts: string[] = []
+
+	for (const value of rawList) {
+		if (value === undefined || value === null) {
+			continue
+		}
+		if (typeof value === 'number') {
+			parts.push(String(value))
+			continue
+		}
+		if (typeof value === 'string') {
+			const chunk = value.trim()
+			if (chunk.length === 0) {
+				continue
+			}
+			parts.push(
+				...chunk
+					.split(',')
+					.map((item) => item.trim())
+					.filter(Boolean),
+			)
+			continue
+		}
+		throw new Error('chapter must be a number or range (e.g. 4, 4-6, 4-*)')
+	}
+
+	if (parts.length === 0) {
+		throw new Error('chapter must include at least one value.')
+	}
+
+	const ranges: ChapterRange[] = []
+	let hasZero = false
+
+	for (const part of parts) {
+		const rangeMatch = part.match(/^(\d+)\s*-\s*(\*|\d+)$/)
+		if (rangeMatch) {
+			const startToken = rangeMatch[1]
+			const endToken = rangeMatch[2]
+			if (!startToken || !endToken) {
+				throw new Error(`Invalid chapter range: "${part}".`)
+			}
+			const start = Number.parseInt(startToken, 10)
+			const end = endToken === '*' ? null : Number.parseInt(endToken, 10)
+
+			if (!Number.isFinite(start)) {
+				throw new Error(`Invalid chapter range start: "${part}".`)
+			}
+			if (end !== null && !Number.isFinite(end)) {
+				throw new Error(`Invalid chapter range end: "${part}".`)
+			}
+			if (start < 0 || (end !== null && end < 0)) {
+				throw new Error(`chapter values must be >= 0: "${part}".`)
+			}
+			if (end !== null && end < start) {
+				throw new Error(`chapter ranges must be low-to-high: "${part}".`)
+			}
+
+			if (start === 0 || end === 0) {
+				hasZero = true
+			}
+			ranges.push({ start, end })
+			continue
+		}
+
+		const singleMatch = part.match(/^\d+$/)
+		if (singleMatch) {
+			const value = Number.parseInt(part, 10)
+			if (!Number.isFinite(value)) {
+				throw new Error(`Invalid chapter value: "${part}".`)
+			}
+			if (value < 0) {
+				throw new Error(`chapter values must be >= 0: "${part}".`)
+			}
+			if (value === 0) {
+				hasZero = true
+			}
+			ranges.push({ start: value, end: value })
+			continue
+		}
+
+		throw new Error(`Invalid chapter value: "${part}".`)
+	}
+
+	return { base: hasZero ? 0 : 1, ranges }
+}
+
+/**
+ * Resolve a chapter selection to an array of zero-based chapter indexes.
+ */
+export function resolveChapterSelection(
+	selection: ChapterSelection,
+	chapterCount: number,
+): number[] {
+	if (!Number.isFinite(chapterCount) || chapterCount <= 0) {
+		throw new Error('Chapter count must be a positive number.')
+	}
+
+	const maxIndex = chapterCount - 1
+	const maxValue = selection.base === 0 ? maxIndex : chapterCount
+	const indexes: number[] = []
+
+	for (const range of selection.ranges) {
+		const startValue = range.start
+		const endValue = range.end === null ? maxValue : range.end
+
+		if (startValue > maxValue) {
+			throw new Error(
+				`chapter range starts at ${startValue}, but only ${chapterCount} chapters exist.`,
+			)
+		}
+		if (endValue > maxValue) {
+			throw new Error(
+				`chapter range ends at ${endValue}, but only ${chapterCount} chapters exist.`,
+			)
+		}
+
+		for (let value = startValue; value <= endValue; value += 1) {
+			const index = selection.base === 0 ? value : value - 1
+			if (index < 0 || index > maxIndex) {
+				throw new Error(
+					`chapter selection ${value} is out of range for ${chapterCount} chapters.`,
+				)
+			}
+			indexes.push(index)
+		}
+	}
+
+	return Array.from(new Set(indexes)).sort((a, b) => a - b)
+}

package/process-course/utils/file-utils.test.ts

@@ -0,0 +1,83 @@
+import { test, expect } from 'bun:test'
+import path from 'node:path'
+import os from 'node:os'
+import { mkdtemp, rm, mkdir, stat } from 'node:fs/promises'
+import { removeDirIfEmpty, safeUnlink } from './file-utils'
+
+async function createTempDir(): Promise<string> {
+	return mkdtemp(path.join(os.tmpdir(), 'file-utils-'))
+}
+
+test('safeUnlink removes existing file', async () => {
+	const tmpDir = await createTempDir()
+	const filePath = path.join(tmpDir, 'sample.txt')
+	try {
+		await Bun.write(filePath, 'hello')
+		expect(await Bun.file(filePath).exists()).toBe(true)
+		await safeUnlink(filePath)
+		expect(await Bun.file(filePath).exists()).toBe(false)
+	} finally {
+		await rm(tmpDir, { recursive: true, force: true })
+	}
+})
+
+test('safeUnlink ignores missing files', async () => {
+	const tmpDir = await createTempDir()
+	const filePath = path.join(tmpDir, 'missing.txt')
+	try {
+		await expect(safeUnlink(filePath)).resolves.toBeUndefined()
+	} finally {
+		await rm(tmpDir, { recursive: true, force: true })
+	}
+})
+
+test('safeUnlink does not remove directories', async () => {
+	const tmpDir = await createTempDir()
+	const nestedDir = path.join(tmpDir, 'nested')
+	try {
+		await mkdir(nestedDir)
+		await expect(safeUnlink(nestedDir)).resolves.toBeUndefined()
+		const stats = await stat(nestedDir)
+		expect(stats.isDirectory()).toBe(true)
+	} finally {
+		await rm(tmpDir, { recursive: true, force: true })
+	}
+})
+
+test('removeDirIfEmpty removes empty directories', async () => {
+	const tmpDir = await createTempDir()
+	const emptyDir = path.join(tmpDir, 'empty')
+	try {
+		await mkdir(emptyDir)
+		const removed = await removeDirIfEmpty(emptyDir)
+		expect(removed).toBe(true)
+		await expect(stat(emptyDir)).rejects.toMatchObject({ code: 'ENOENT' })
+	} finally {
+		await rm(tmpDir, { recursive: true, force: true })
+	}
+})
+
+test('removeDirIfEmpty keeps directories with files', async () => {
+	const tmpDir = await createTempDir()
+	const filledDir = path.join(tmpDir, 'filled')
+	try {
+		await mkdir(filledDir)
+		await Bun.write(path.join(filledDir, 'sample.txt'), 'data')
+		const removed = await removeDirIfEmpty(filledDir)
+		expect(removed).toBe(false)
+		const stats = await stat(filledDir)
+		expect(stats.isDirectory()).toBe(true)
+	} finally {
+		await rm(tmpDir, { recursive: true, force: true })
+	}
+})
+
+test('removeDirIfEmpty ignores missing directories', async () => {
+	const tmpDir = await createTempDir()
+	const missingDir = path.join(tmpDir, 'missing')
+	try {
+		await expect(removeDirIfEmpty(missingDir)).resolves.toBe(false)
+	} finally {
+		await rm(tmpDir, { recursive: true, force: true })
+	}
+})

package/process-course/utils/file-utils.ts

@@ -0,0 +1,57 @@
+import { readdir, rmdir, unlink } from 'node:fs/promises'
+import { logInfo } from '../logging'
+
+/**
+ * Safely delete a file, ignoring ENOENT errors.
+ */
+export async function safeUnlink(filePath: string): Promise<void> {
+	try {
+		await unlink(filePath)
+	} catch (error) {
+		if (error && typeof error === 'object' && 'code' in error) {
+			if (error.code === 'ENOENT') {
+				return
+			}
+		}
+		logInfo(
+			`Failed to delete ${filePath}: ${error instanceof Error ? error.message : error}`,
+		)
+	}
+}
+
+/**
+ * Remove a directory if it exists and is empty.
+ */
+export async function removeDirIfEmpty(dirPath: string): Promise<boolean> {
+	try {
+		const entries = await readdir(dirPath)
+		if (entries.length > 0) {
+			return false
+		}
+	} catch (error) {
+		if (error && typeof error === 'object' && 'code' in error) {
+			if (error.code === 'ENOENT') {
+				return false
+			}
+		}
+		logInfo(
+			`Failed to read directory ${dirPath}: ${error instanceof Error ? error.message : error}`,
+		)
+		return false
+	}
+
+	try {
+		await rmdir(dirPath)
+		return true
+	} catch (error) {
+		if (error && typeof error === 'object' && 'code' in error) {
+			if (error.code === 'ENOENT' || error.code === 'ENOTEMPTY') {
+				return false
+			}
+		}
+		logInfo(
+			`Failed to remove directory ${dirPath}: ${error instanceof Error ? error.message : error}`,
+		)
+		return false
+	}
+}

package/process-course/utils/filename.test.ts

@@ -0,0 +1,27 @@
+import { test, expect } from 'bun:test'
+import type { Chapter } from '../types'
+import { formatChapterFilename } from './filename'
+
+function createChapter(index: number, title?: string): Chapter {
+	return {
+		index,
+		start: 0,
+		end: 10,
+		title: title as string,
+	}
+}
+
+test('formatChapterFilename uses padded index and kebab-case title', () => {
+	const chapter = createChapter(0, 'Intro to React')
+	expect(formatChapterFilename(chapter)).toBe('chapter-01-intro-to-react')
+})
+
+test('formatChapterFilename falls back to chapter-N when title missing', () => {
+	const chapter = createChapter(2, undefined)
+	expect(formatChapterFilename(chapter)).toBe('chapter-03-chapter-3')
+})
+
+test('formatChapterFilename normalizes number words and dots', () => {
+	const chapter = createChapter(0, 'Lesson One point Five')
+	expect(formatChapterFilename(chapter)).toBe('chapter-01-lesson-0105')
+})

package/process-course/utils/filename.ts

@@ -0,0 +1,12 @@
+import type { Chapter } from '../types'
+import { normalizeFilename, toKebabCase } from '../../utils'
+
+/**
+ * Format a chapter into a filename-safe string.
+ */
+export function formatChapterFilename(chapter: Chapter): string {
+	const title = chapter.title ?? `chapter-${chapter.index + 1}`
+	const normalized = normalizeFilename(title)
+	const slug = toKebabCase(normalized)
+	return `chapter-${String(chapter.index + 1).padStart(2, '0')}-${slug}`
+}