@thegetty/quire-cli 1.0.0-rc.35 → 1.0.0-rc.37

package/src/lib/epub/index.test.js

@@ -0,0 +1,518 @@
+import esmock from 'esmock'
+import path from 'node:path'
+import sinon from 'sinon'
+import test from 'ava'
+
+/**
+ * EPUB Module Integration Tests
+ *
+ * Tests the EPUB generation façade module behavior with mocked dependencies.
+ * Uses esmock to isolate the module from file system and external EPUB tools.
+ */
+
+/**
+ * Create a cross-platform absolute path for testing
+ * @param {...string} segments - Path segments to join
+ * @returns {string} Platform-appropriate absolute path
+ */
+function testPath(...segments) {
+  const root = process.platform === 'win32' ? 'C:\\' : '/'
+  return path.join(root, ...segments)
+}
+
+test.beforeEach((t) => {
+  t.context.sandbox = sinon.createSandbox()
+})
+
+test.afterEach.always((t) => {
+  t.context.sandbox.restore()
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Library resolution tests
+// ─────────────────────────────────────────────────────────────────────────────
+
+test('generateEpub resolves epubjs library correctly', async (t) => {
+  const { sandbox } = t.context
+
+  const mockEpubLib = sandbox.stub().resolves()
+  const mockDynamicImport = sandbox.stub().resolves({ default: mockEpubLib })
+
+  const mockPaths = {
+    getProjectRoot: () => testPath('project'),
+    getEpubDir: () => '_epub'
+  }
+
+  const mockFs = {
+    existsSync: sandbox.stub().returns(true),
+    mkdirSync: sandbox.stub()
+  }
+
+  const mockReporter = {
+    start: sandbox.stub(),
+    detail: sandbox.stub(),
+    succeed: sandbox.stub(),
+    fail: sandbox.stub()
+  }
+
+  const generateEpub = await esmock('./index.js', {
+    '#helpers/os-utils.js': { dynamicImport: mockDynamicImport },
+    '#lib/project/index.js': mockPaths,
+    'fs-extra': mockFs,
+    '#lib/reporter/index.js': { default: mockReporter }
+  })
+
+  await generateEpub.default({ lib: 'epubjs' })
+
+  t.true(mockDynamicImport.calledOnce)
+  t.true(mockDynamicImport.firstCall.args[0].includes('epub.js'))
+  t.true(mockReporter.start.calledWith(sinon.match(/Epub\.js/)))
+})
+
+test('generateEpub resolves pandoc library correctly', async (t) => {
+  const { sandbox } = t.context
+
+  const mockEpubLib = sandbox.stub().resolves()
+  const mockDynamicImport = sandbox.stub().resolves({ default: mockEpubLib })
+  const mockWhich = sandbox.stub().returns('/usr/local/bin/pandoc')
+
+  const mockPaths = {
+    getProjectRoot: () => testPath('project'),
+    getEpubDir: () => '_epub'
+  }
+
+  const mockFs = {
+    existsSync: sandbox.stub().returns(true),
+    mkdirSync: sandbox.stub()
+  }
+
+  const mockReporter = {
+    start: sandbox.stub(),
+    detail: sandbox.stub(),
+    succeed: sandbox.stub(),
+    fail: sandbox.stub()
+  }
+
+  const generateEpub = await esmock('./index.js', {
+    '#helpers/os-utils.js': { dynamicImport: mockDynamicImport },
+    '#helpers/which.js': { default: mockWhich },
+    '#lib/project/index.js': mockPaths,
+    'fs-extra': mockFs,
+    '#lib/reporter/index.js': { default: mockReporter }
+  })
+
+  await generateEpub.default({ lib: 'pandoc' })
+
+  t.true(mockDynamicImport.firstCall.args[0].includes('pandoc.js'))
+  t.true(mockReporter.start.calledWith(sinon.match(/Pandoc/)))
+})
+
+test('generateEpub normalizes library name variations', async (t) => {
+  const { sandbox } = t.context
+
+  const mockEpubLib = sandbox.stub().resolves()
+  const mockDynamicImport = sandbox.stub().resolves({ default: mockEpubLib })
+  const mockWhich = sandbox.stub().returns('/usr/local/bin/pandoc')
+
+  const mockPaths = {
+    getProjectRoot: () => testPath('project'),
+    getEpubDir: () => '_epub'
+  }
+
+  const mockFs = {
+    existsSync: sandbox.stub().returns(true),
+    mkdirSync: sandbox.stub()
+  }
+
+  const mockReporter = {
+    start: sandbox.stub(),
+    detail: sandbox.stub(),
+    succeed: sandbox.stub(),
+    fail: sandbox.stub()
+  }
+
+  const generateEpub = await esmock('./index.js', {
+    '#helpers/os-utils.js': { dynamicImport: mockDynamicImport },
+    '#helpers/which.js': { default: mockWhich },
+    '#lib/project/index.js': mockPaths,
+    'fs-extra': mockFs,
+    '#lib/reporter/index.js': { default: mockReporter }
+  })
+
+  // Test "epub-js" variant (with hyphen)
+  await generateEpub.default({ lib: 'epub-js' })
+  t.true(mockDynamicImport.firstCall.args[0].includes('epub.js'))
+
+  // Test "PANDOC" variant (uppercase)
+  mockDynamicImport.resetHistory()
+  await generateEpub.default({ lib: 'PANDOC' })
+  t.true(mockDynamicImport.firstCall.args[0].includes('pandoc.js'))
+})
+
+test('generateEpub defaults to epubjs when no library specified', async (t) => {
+  const { sandbox } = t.context
+
+  const mockEpubLib = sandbox.stub().resolves()
+  const mockDynamicImport = sandbox.stub().resolves({ default: mockEpubLib })
+
+  const mockPaths = {
+    getProjectRoot: () => testPath('project'),
+    getEpubDir: () => '_epub'
+  }
+
+  const mockFs = {
+    existsSync: sandbox.stub().returns(true),
+    mkdirSync: sandbox.stub()
+  }
+
+  const mockReporter = {
+    start: sandbox.stub(),
+    detail: sandbox.stub(),
+    succeed: sandbox.stub(),
+    fail: sandbox.stub()
+  }
+
+  const generateEpub = await esmock('./index.js', {
+    '#helpers/os-utils.js': { dynamicImport: mockDynamicImport },
+    '#lib/project/index.js': mockPaths,
+    'fs-extra': mockFs,
+    '#lib/reporter/index.js': { default: mockReporter }
+  })
+
+  await generateEpub.default({})
+
+  t.true(mockDynamicImport.firstCall.args[0].includes('epub.js'))
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Error handling tests
+// ─────────────────────────────────────────────────────────────────────────────
+
+test('generateEpub throws InvalidEpubLibraryError for unrecognized library', async (t) => {
+  const { sandbox } = t.context
+
+  const mockPaths = {
+    getProjectRoot: () => testPath('project'),
+    getEpubDir: () => '_epub'
+  }
+
+  const mockReporter = {
+    start: sandbox.stub(),
+    detail: sandbox.stub(),
+    succeed: sandbox.stub(),
+    fail: sandbox.stub()
+  }
+
+  const generateEpub = await esmock('./index.js', {
+    '#helpers/os-utils.js': { dynamicImport: sandbox.stub() },
+    '#lib/project/index.js': mockPaths,
+    'fs-extra': { existsSync: sandbox.stub(), mkdirSync: sandbox.stub() },
+    '#lib/reporter/index.js': { default: mockReporter }
+  })
+
+  const error = await t.throwsAsync(() => generateEpub.default({ lib: 'unknown-library' }))
+
+  t.is(error.code, 'INVALID_EPUB_LIBRARY')
+  t.true(error.message.includes('unknown-library'))
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Output path tests
+// ─────────────────────────────────────────────────────────────────────────────
+
+test('generateEpub uses default output path based on library name', async (t) => {
+  const { sandbox } = t.context
+
+  const mockEpubLib = sandbox.stub().resolves()
+  const mockDynamicImport = sandbox.stub().resolves({ default: mockEpubLib })
+
+  const mockPaths = {
+    getProjectRoot: () => testPath('project'),
+    getEpubDir: () => '_epub'
+  }
+
+  const mockFs = {
+    existsSync: sandbox.stub().returns(true),
+    mkdirSync: sandbox.stub()
+  }
+
+  const mockReporter = {
+    start: sandbox.stub(),
+    detail: sandbox.stub(),
+    succeed: sandbox.stub(),
+    fail: sandbox.stub()
+  }
+
+  const generateEpub = await esmock('./index.js', {
+    '#helpers/os-utils.js': { dynamicImport: mockDynamicImport },
+    '#lib/project/index.js': mockPaths,
+    'fs-extra': mockFs,
+    '#lib/reporter/index.js': { default: mockReporter }
+  })
+
+  const output = await generateEpub.default({ lib: 'epubjs' })
+
+  t.is(output, path.join(testPath('project'), 'epubjs.epub'))
+})
+
+test('generateEpub uses custom output path when provided', async (t) => {
+  const { sandbox } = t.context
+
+  const mockEpubLib = sandbox.stub().resolves()
+  const mockDynamicImport = sandbox.stub().resolves({ default: mockEpubLib })
+
+  const mockPaths = {
+    getProjectRoot: () => testPath('project'),
+    getEpubDir: () => '_epub'
+  }
+
+  const mockFs = {
+    existsSync: sandbox.stub().returns(true),
+    mkdirSync: sandbox.stub()
+  }
+
+  const mockReporter = {
+    start: sandbox.stub(),
+    detail: sandbox.stub(),
+    succeed: sandbox.stub(),
+    fail: sandbox.stub()
+  }
+
+  const generateEpub = await esmock('./index.js', {
+    '#helpers/os-utils.js': { dynamicImport: mockDynamicImport },
+    '#lib/project/index.js': mockPaths,
+    'fs-extra': mockFs,
+    '#lib/reporter/index.js': { default: mockReporter }
+  })
+
+  const output = await generateEpub.default({ lib: 'epubjs', output: 'my-book.epub' })
+
+  t.is(output, path.join(testPath('project'), 'my-book.epub'))
+})
+
+test('generateEpub resolves relative output path against project root', async (t) => {
+  const { sandbox } = t.context
+
+  const mockEpubLib = sandbox.stub().resolves()
+  const mockDynamicImport = sandbox.stub().resolves({ default: mockEpubLib })
+
+  const mockPaths = {
+    getProjectRoot: () => testPath('project'),
+    getEpubDir: () => '_epub'
+  }
+
+  const mockFs = {
+    existsSync: sandbox.stub().returns(true),
+    mkdirSync: sandbox.stub()
+  }
+
+  const mockReporter = {
+    start: sandbox.stub(),
+    detail: sandbox.stub(),
+    succeed: sandbox.stub(),
+    fail: sandbox.stub()
+  }
+
+  const generateEpub = await esmock('./index.js', {
+    '#helpers/os-utils.js': { dynamicImport: mockDynamicImport },
+    '#lib/project/index.js': mockPaths,
+    'fs-extra': mockFs,
+    '#lib/reporter/index.js': { default: mockReporter }
+  })
+
+  const output = await generateEpub.default({ lib: 'epubjs', output: '_downloads/book' })
+
+  t.is(output, path.join(testPath('project'), '_downloads', 'book.epub'))
+})
+
+test('generateEpub uses absolute output path directly', async (t) => {
+  const { sandbox } = t.context
+
+  const mockEpubLib = sandbox.stub().resolves()
+  const mockDynamicImport = sandbox.stub().resolves({ default: mockEpubLib })
+
+  const mockPaths = {
+    getProjectRoot: () => testPath('project'),
+    getEpubDir: () => '_epub'
+  }
+
+  const mockFs = {
+    existsSync: sandbox.stub().returns(true),
+    mkdirSync: sandbox.stub()
+  }
+
+  const mockReporter = {
+    start: sandbox.stub(),
+    detail: sandbox.stub(),
+    succeed: sandbox.stub(),
+    fail: sandbox.stub()
+  }
+
+  const generateEpub = await esmock('./index.js', {
+    '#helpers/os-utils.js': { dynamicImport: mockDynamicImport },
+    '#lib/project/index.js': mockPaths,
+    'fs-extra': mockFs,
+    '#lib/reporter/index.js': { default: mockReporter }
+  })
+
+  const customPath = testPath('custom', 'path', 'book.epub')
+  const output = await generateEpub.default({ lib: 'epubjs', output: customPath })
+
+  t.is(output, customPath)
+})
+
+test('generateEpub adds .epub extension if missing', async (t) => {
+  const { sandbox } = t.context
+
+  const mockEpubLib = sandbox.stub().resolves()
+  const mockDynamicImport = sandbox.stub().resolves({ default: mockEpubLib })
+
+  const mockPaths = {
+    getProjectRoot: () => testPath('project'),
+    getEpubDir: () => '_epub'
+  }
+
+  const mockFs = {
+    existsSync: sandbox.stub().returns(true),
+    mkdirSync: sandbox.stub()
+  }
+
+  const mockReporter = {
+    start: sandbox.stub(),
+    detail: sandbox.stub(),
+    succeed: sandbox.stub(),
+    fail: sandbox.stub()
+  }
+
+  const generateEpub = await esmock('./index.js', {
+    '#helpers/os-utils.js': { dynamicImport: mockDynamicImport },
+    '#lib/project/index.js': mockPaths,
+    'fs-extra': mockFs,
+    '#lib/reporter/index.js': { default: mockReporter }
+  })
+
+  const output = await generateEpub.default({ lib: 'epubjs', output: 'my-book' })
+
+  t.is(output, path.join(testPath('project'), 'my-book.epub'))
+})
+
+test('generateEpub creates output directory if missing', async (t) => {
+  const { sandbox } = t.context
+
+  const mockEpubLib = sandbox.stub().resolves()
+  const mockDynamicImport = sandbox.stub().resolves({ default: mockEpubLib })
+
+  const mockPaths = {
+    getProjectRoot: () => testPath('project'),
+    getEpubDir: () => '_epub'
+  }
+
+  const mockFs = {
+    existsSync: sandbox.stub().returns(false),
+    mkdirSync: sandbox.stub()
+  }
+
+  const mockReporter = {
+    start: sandbox.stub(),
+    detail: sandbox.stub(),
+    succeed: sandbox.stub(),
+    fail: sandbox.stub()
+  }
+
+  const generateEpub = await esmock('./index.js', {
+    '#helpers/os-utils.js': { dynamicImport: mockDynamicImport },
+    '#lib/project/index.js': mockPaths,
+    'fs-extra': mockFs,
+    '#lib/reporter/index.js': { default: mockReporter }
+  })
+
+  await generateEpub.default({ lib: 'epubjs', output: '_downloads/book.epub' })
+
+  t.true(mockFs.mkdirSync.calledOnce)
+  t.is(mockFs.mkdirSync.firstCall.args[0], path.join(testPath('project'), '_downloads'))
+  t.deepEqual(mockFs.mkdirSync.firstCall.args[1], { recursive: true })
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// EPUB library invocation tests
+// ─────────────────────────────────────────────────────────────────────────────
+
+test('generateEpub passes correct arguments to EPUB library', async (t) => {
+  const { sandbox } = t.context
+
+  const mockEpubLib = sandbox.stub().resolves()
+  const mockDynamicImport = sandbox.stub().resolves({ default: mockEpubLib })
+
+  const mockPaths = {
+    getProjectRoot: () => testPath('project'),
+    getEpubDir: () => '_epub'
+  }
+
+  const mockFs = {
+    existsSync: sandbox.stub().returns(true),
+    mkdirSync: sandbox.stub()
+  }
+
+  const mockReporter = {
+    start: sandbox.stub(),
+    detail: sandbox.stub(),
+    succeed: sandbox.stub(),
+    fail: sandbox.stub()
+  }
+
+  const generateEpub = await esmock('./index.js', {
+    '#helpers/os-utils.js': { dynamicImport: mockDynamicImport },
+    '#lib/project/index.js': mockPaths,
+    'fs-extra': mockFs,
+    '#lib/reporter/index.js': { default: mockReporter }
+  })
+
+  await generateEpub.default({ lib: 'epubjs', debug: true })
+
+  t.true(mockEpubLib.calledOnce)
+  const [input, output, options] = mockEpubLib.firstCall.args
+  t.is(input, path.join(testPath('project'), '_epub'))
+  t.is(output, path.join(testPath('project'), 'epubjs.epub'))
+  t.true(options.debug)
+})
+
+test('generateEpub passes options through to EPUB library', async (t) => {
+  const { sandbox } = t.context
+
+  const mockEpubLib = sandbox.stub().resolves()
+  const mockDynamicImport = sandbox.stub().resolves({ default: mockEpubLib })
+
+  const mockPaths = {
+    getProjectRoot: () => testPath('project'),
+    getEpubDir: () => '_epub'
+  }
+
+  const mockFs = {
+    existsSync: sandbox.stub().returns(true),
+    mkdirSync: sandbox.stub()
+  }
+
+  const mockReporter = {
+    start: sandbox.stub(),
+    detail: sandbox.stub(),
+    succeed: sandbox.stub(),
+    fail: sandbox.stub()
+  }
+
+  const generateEpub = await esmock('./index.js', {
+    '#helpers/os-utils.js': { dynamicImport: mockDynamicImport },
+    '#lib/project/index.js': mockPaths,
+    'fs-extra': mockFs,
+    '#lib/reporter/index.js': { default: mockReporter }
+  })
+
+  await generateEpub.default({
+    lib: 'epubjs',
+    debug: true,
+    customOption: 'value'
+  })
+
+  const [, , options] = mockEpubLib.firstCall.args
+  t.true(options.debug)
+  t.is(options.customOption, 'value')
+})

package/src/lib/epub/pandoc.js

@@ -1,8 +1,14 @@
 import { execa } from 'execa'
 import fs from 'fs-extra'
 import path from 'node:path'
-import paths, { projectRoot } from '#lib/11ty/paths.js'
-import which from '#helpers/which.js'
+import { EpubGenerationError } from '#src/errors/index.js'
+import createDebug from '#debug'
+import ENGINES from './engines.js'
+
+const debug = createDebug('lib:epub:pandoc')
+
+/** Re-export engine metadata from central registry */
+export const metadata = ENGINES.pandoc
 
 /**
  * Filter directory entries for XHTML files
@@ -19,9 +25,18 @@ const xhtmlFiles = (dirent) => {
 /**
  * A façade module for interacting with Pandoc CLI.
  * @see https://pandoc.org/MANUAL.html#general-options
+ *
+ * Pandoc availability is checked by the parent façade (lib/epub/index.js)
+ * before this module is loaded, so we can assume pandoc is in PATH.
+ *
+ * @param {string} input - Path to the input directory containing XHTML files
+ * @param {string} output - Path where the EPUB should be written
+ * @param {Object} [options={}] - Generation options
+ * @returns {Promise<void>}
  */
 export default async (input, output, options = {}) => {
-  which('pandoc')
+  debug('input: %s', input)
+  debug('output: %s', output)
 
   const inputs = fs.readdirSync(input)
     .map((entry) => path.join(input, entry))
@@ -38,5 +53,19 @@ export default async (input, output, options = {}) => {
     `--standalone`,
   ]
 
-  await execa('pandoc', [...cmdOptions, ...inputs])
+  debug('cmd options: %O', cmdOptions)
+  debug('inputs: %d XHTML files', inputs.length)
+
+  try {
+    const { stderr } = await execa('pandoc', [...cmdOptions, ...inputs])
+    // Pandoc may emit warnings to stderr even on success
+    if (stderr) {
+      debug('pandoc stderr: %s', stderr)
+    }
+  } catch (error) {
+    const details = error.stderr || error.message
+    throw new EpubGenerationError(`Pandoc EPUB generation failed: ${details}`)
+  }
+
+  debug('complete')
 }

package/src/lib/epub/pandoc.test.js

@@ -0,0 +1,122 @@
+import esmock from 'esmock'
+import path from 'node:path'
+import sinon from 'sinon'
+import test from 'ava'
+
+/**
+ * Pandoc EPUB Engine Integration Tests
+ *
+ * Tests error handling and logging paths that are difficult to trigger in E2E tests.
+ * The happy path is covered by E2E tests with real Pandoc installation.
+ */
+
+/**
+ * Create a cross-platform absolute path for testing
+ * @param {...string} segments - Path segments to join
+ * @returns {string} Platform-appropriate absolute path
+ */
+function testPath(...segments) {
+  const root = process.platform === 'win32' ? 'C:\\' : '/'
+  return path.join(root, ...segments)
+}
+
+test.beforeEach((t) => {
+  t.context.sandbox = sinon.createSandbox()
+
+  // Mock fs-extra
+  t.context.mockFs = {
+    readdirSync: t.context.sandbox.stub().returns(['chapter1.xhtml', 'chapter2.xhtml']),
+    lstatSync: t.context.sandbox.stub().returns({ isFile: () => true })
+  }
+})
+
+test.afterEach.always((t) => {
+  t.context.sandbox.restore()
+})
+
+test('pandoc logs stderr via debug when present', async (t) => {
+  const { sandbox, mockFs } = t.context
+
+  const mockExeca = sandbox.stub().resolves({ stderr: 'warning: deprecated option used' })
+  const mockDebug = sandbox.stub()
+  const mockCreateDebug = sandbox.stub().returns(mockDebug)
+
+  const pandoc = await esmock('./pandoc.js', {
+    execa: { execa: mockExeca },
+    'fs-extra': mockFs,
+    '#debug': { default: mockCreateDebug }
+  })
+
+  await pandoc.default(testPath('input'), testPath('output.epub'), {})
+
+  t.true(mockDebug.calledWith('pandoc stderr: %s', 'warning: deprecated option used'))
+})
+
+test('pandoc does not log stderr when empty', async (t) => {
+  const { sandbox, mockFs } = t.context
+
+  const mockExeca = sandbox.stub().resolves({ stderr: '' })
+  const mockDebug = sandbox.stub()
+  const mockCreateDebug = sandbox.stub().returns(mockDebug)
+
+  const pandoc = await esmock('./pandoc.js', {
+    execa: { execa: mockExeca },
+    'fs-extra': mockFs,
+    '#debug': { default: mockCreateDebug }
+  })
+
+  await pandoc.default(testPath('input'), testPath('output.epub'), {})
+
+  t.false(mockDebug.calledWith(sinon.match('pandoc stderr')))
+})
+
+test('pandoc throws EpubGenerationError when execa fails', async (t) => {
+  const { sandbox, mockFs } = t.context
+
+  const execaError = new Error('Pandoc failed')
+  execaError.stderr = 'error: unknown input format'
+
+  const mockExeca = sandbox.stub().rejects(execaError)
+
+  const pandoc = await esmock('./pandoc.js', {
+    execa: { execa: mockExeca },
+    'fs-extra': mockFs
+  })
+
+  const error = await t.throwsAsync(() =>
+    pandoc.default(testPath('input'), testPath('output.epub'), {})
+  )
+
+  t.is(error.code, 'EPUB_FAILED')
+  // EpubGenerationError formats message as: "EPUB generation failed: <details>"
+  // where <details> includes tool name, operation, and stderr/message
+  t.true(error.message.includes('EPUB generation failed'))
+  t.true(error.message.includes('Pandoc'))
+  t.true(error.message.includes('unknown input format'))
+})
+
+test('pandoc filters only XHTML files from input directory', async (t) => {
+  const { sandbox } = t.context
+
+  const mockExeca = sandbox.stub().resolves({ stderr: '' })
+
+  // Mock readdirSync to return mixed files
+  const mockFs = {
+    readdirSync: sandbox.stub().returns(['chapter1.xhtml', 'image.png', 'chapter2.xhtml', 'style.css']),
+    lstatSync: sandbox.stub().returns({ isFile: () => true })
+  }
+
+  const pandoc = await esmock('./pandoc.js', {
+    execa: { execa: mockExeca },
+    'fs-extra': mockFs
+  })
+
+  await pandoc.default(testPath('input'), testPath('output.epub'), {})
+
+  // Verify only XHTML files were passed to pandoc
+  const [, args] = mockExeca.firstCall.args
+  const inputFiles = args.filter(arg => arg.endsWith('.xhtml'))
+  t.is(inputFiles.length, 2)
+  t.true(inputFiles[0].endsWith('chapter1.xhtml'))
+  t.true(inputFiles[1].endsWith('chapter2.xhtml'))
+})