@thegetty/quire-cli 1.0.0-rc.36 → 1.0.0-rc.38

package/src/lib/doctor/checks/environment/runtime-info.js

@@ -0,0 +1,51 @@
+/**
+ * Node.js runtime info check
+ *
+ * Reports V8 heap limit and environment variables relevant to
+ * troubleshooting (NODE_OPTIONS, shell, locale). This is an
+ * informational check that always passes.
+ *
+ * @module lib/doctor/checks/environment/runtime-info
+ */
+import v8 from 'node:v8'
+import createDebug from '#debug'
+import { getPlatform, Platform } from '#lib/platform.js'
+
+const debug = createDebug('lib:doctor:runtime-info')
+
+/**
+ * Report Node.js runtime information
+ *
+ * Surfaces the V8 heap size limit (which determines when large Quire
+ * builds hit OOM errors) and environment variables that affect CLI
+ * behavior: NODE_OPTIONS, shell, and locale.
+ *
+ * @returns {import('../../index.js').CheckResult}
+ */
+export function checkRuntimeInfo() {
+  const heapStats = v8.getHeapStatistics()
+  const heapLimitMB = Math.round(heapStats.heap_size_limit / 1024 / 1024)
+
+  const platform = getPlatform()
+  const shell = platform === Platform.WINDOWS
+    ? process.env.COMSPEC || '(not set)'
+    : process.env.SHELL || '(not set)'
+  const nodeOptions = process.env.NODE_OPTIONS || '(not set)'
+  const locale = process.env.LANG || process.env.LC_ALL || '(not set)'
+
+  debug('Heap limit: %d MB, NODE_OPTIONS: %s, Shell: %s, Locale: %s', heapLimitMB, nodeOptions, shell, locale)
+
+  const detailParts = [
+    `NODE_OPTIONS: ${nodeOptions}`,
+    `Shell: ${shell}`,
+    `Locale: ${locale}`,
+  ]
+
+  return {
+    ok: true,
+    message: `Heap limit: ${heapLimitMB} MB`,
+    details: detailParts.join(', '),
+  }
+}
+
+export default checkRuntimeInfo

package/src/lib/doctor/checks/environment/runtime-info.test.js

@@ -0,0 +1,132 @@
+import test from 'ava'
+import sinon from 'sinon'
+import esmock from 'esmock'
+
+test.beforeEach((t) => {
+  t.context.sandbox = sinon.createSandbox()
+})
+
+test.afterEach.always((t) => {
+  t.context.sandbox.restore()
+})
+
+test('checkRuntimeInfo returns ok with heap limit', async (t) => {
+  const { sandbox } = t.context
+
+  const { checkRuntimeInfo } = await esmock('./runtime-info.js', {
+    'node:v8': {
+      getHeapStatistics: sandbox.stub().returns({
+        heap_size_limit: 4 * 1024 * 1024 * 1024, // 4 GB
+      }),
+    },
+    '#lib/platform.js': {
+      getPlatform: sandbox.stub().returns('macos'),
+      Platform: { MACOS: 'macos', WINDOWS: 'windows', LINUX: 'linux' },
+    },
+  })
+
+  const result = checkRuntimeInfo()
+
+  t.true(result.ok)
+  t.regex(result.message, /Heap limit: 4096 MB/)
+  t.is(typeof result.details, 'string')
+})
+
+test('checkRuntimeInfo includes NODE_OPTIONS in details', async (t) => {
+  const { sandbox } = t.context
+
+  const { checkRuntimeInfo } = await esmock('./runtime-info.js', {
+    'node:v8': {
+      getHeapStatistics: sandbox.stub().returns({
+        heap_size_limit: 8 * 1024 * 1024 * 1024,
+      }),
+    },
+    '#lib/platform.js': {
+      getPlatform: sandbox.stub().returns('macos'),
+      Platform: { MACOS: 'macos', WINDOWS: 'windows', LINUX: 'linux' },
+    },
+  })
+
+  const result = checkRuntimeInfo()
+
+  // NODE_OPTIONS should appear in details (either the actual value or '(not set)')
+  t.true(result.details.includes('NODE_OPTIONS:'))
+  t.true(result.details.includes('Shell:'))
+  t.true(result.details.includes('Locale:'))
+})
+
+test('checkRuntimeInfo shows (not set) for missing env vars', async (t) => {
+  const { sandbox } = t.context
+
+  const originalNodeOptions = process.env.NODE_OPTIONS
+  const originalShell = process.env.SHELL
+  const originalLang = process.env.LANG
+  const originalLcAll = process.env.LC_ALL
+
+  delete process.env.NODE_OPTIONS
+  delete process.env.SHELL
+  delete process.env.LANG
+  delete process.env.LC_ALL
+
+  try {
+    const { checkRuntimeInfo } = await esmock('./runtime-info.js', {
+      'node:v8': {
+        getHeapStatistics: sandbox.stub().returns({
+          heap_size_limit: 4 * 1024 * 1024 * 1024,
+        }),
+      },
+      '#lib/platform.js': {
+        getPlatform: sandbox.stub().returns('linux'),
+        Platform: { MACOS: 'macos', WINDOWS: 'windows', LINUX: 'linux' },
+      },
+    })
+
+    const result = checkRuntimeInfo()
+
+    t.true(result.details.includes('NODE_OPTIONS: (not set)'))
+    t.true(result.details.includes('Shell: (not set)'))
+    t.true(result.details.includes('Locale: (not set)'))
+  } finally {
+    if (originalNodeOptions !== undefined) process.env.NODE_OPTIONS = originalNodeOptions
+    if (originalShell !== undefined) process.env.SHELL = originalShell
+    if (originalLang !== undefined) process.env.LANG = originalLang
+    if (originalLcAll !== undefined) process.env.LC_ALL = originalLcAll
+  }
+})
+
+test('checkRuntimeInfo uses COMSPEC on Windows', async (t) => {
+  const { sandbox } = t.context
+
+  const originalShell = process.env.SHELL
+  const originalComspec = process.env.COMSPEC
+
+  delete process.env.SHELL
+  process.env.COMSPEC = 'C:\\Windows\\System32\\cmd.exe'
+
+  try {
+    const { checkRuntimeInfo } = await esmock('./runtime-info.js', {
+      'node:v8': {
+        getHeapStatistics: sandbox.stub().returns({
+          heap_size_limit: 4 * 1024 * 1024 * 1024,
+        }),
+      },
+      '#lib/platform.js': {
+        getPlatform: sandbox.stub().returns('windows'),
+        Platform: { MACOS: 'macos', WINDOWS: 'windows', LINUX: 'linux' },
+      },
+    })
+
+    const result = checkRuntimeInfo()
+
+    t.true(result.details.includes('Shell: C:\\Windows\\System32\\cmd.exe'))
+  } finally {
+    if (originalShell !== undefined) {
+      process.env.SHELL = originalShell
+    }
+    if (originalComspec !== undefined) {
+      process.env.COMSPEC = originalComspec
+    } else {
+      delete process.env.COMSPEC
+    }
+  }
+})

package/src/lib/doctor/checks/outputs/epub-output.js

@@ -0,0 +1,119 @@
+/**
+ * EPUB output check
+ *
+ * Checks for EPUB output files using the same path resolution logic as the
+ * EPUB generation command.
+ *
+ * @module lib/doctor/checks/outputs/epub-output
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import createDebug from '#debug'
+import { getEpubOutputPaths } from '#lib/project/output-paths.js'
+import config from '#lib/conf/config.js'
+import { getStatus } from '#lib/conf/build-status.js'
+import { DOCS_BASE_URL, resolveStaleThreshold } from '#lib/doctor/constants.js'
+import { formatDuration } from '#lib/doctor/formatDuration.js'
+
+const debug = createDebug('lib:doctor:epub-output')
+
+/**
+ * Check if EPUB output exists and is up to date with _site
+ *
+ * EPUB output is a final .epub file ({engine}.epub, e.g. epubjs.epub,
+ * pandoc.epub). Uses the same path resolution as `commands/epub.js`.
+ *
+ * @returns {import('../../index.js').CheckResult}
+ */
+export function checkEpubOutput() {
+  const candidatePaths = getEpubOutputPaths()
+  debug('candidate EPUB paths: %o', candidatePaths)
+
+  // Find which .epub files actually exist
+  const existingEpubs = candidatePaths.filter((p) => fs.existsSync(p))
+
+  // No EPUB output
+  if (existingEpubs.length === 0) {
+    debug('No EPUB files found, checking stored epub status')
+
+    const status = getStatus(process.cwd(), 'epub')
+    if (status?.status === 'failed') {
+      debug('Last epub generation failed (stored status)')
+      return {
+        ok: false,
+        message: 'Last EPUB generation failed',
+        remediation: `The last "quire epub" run failed. Check the output for errors and try again.
+    • Run "quire epub --debug" for detailed error output`,
+        docsUrl: `${DOCS_BASE_URL}/quire-commands/#epub`,
+      }
+    }
+
+    return {
+      ok: true,
+      level: 'na',
+      message: 'No EPUB output found',
+      remediation: `Run "quire epub" to generate an EPUB.
+    • If you already ran "quire epub" and it failed, check the output for errors`,
+      docsUrl: `${DOCS_BASE_URL}/quire-commands/#epub`,
+    }
+  }
+
+  // Use basenames for display
+  const existingNames = existingEpubs.map((p) => path.basename(p))
+  debug('found EPUB files: %o', existingNames)
+
+  // Check if _site exists for staleness comparison
+  if (!fs.existsSync('_site')) {
+    debug('_site directory not found')
+    return {
+      ok: true,
+      message: `${existingNames.join(', ')} exists (no _site to compare)`,
+    }
+  }
+
+  // Get _site last modified time
+  const { mtimeMs: siteLastModified } = fs.statSync('_site')
+  debug('_site lastModified: %d', siteLastModified)
+
+  // Check each .epub file for staleness beyond the configured threshold
+  const thresholdMs = resolveStaleThreshold(config.get('staleThreshold'))
+  const staleFiles = []
+  let oldestEpubLastModified = Infinity
+
+  for (const epubFile of existingEpubs) {
+    const { mtimeMs: epubLastModified } = fs.statSync(epubFile)
+    debug('%s lastModified: %d', path.basename(epubFile), epubLastModified)
+
+    const staleDelta = siteLastModified - epubLastModified
+    if (staleDelta > thresholdMs) {
+      staleFiles.push(epubFile)
+      if (epubLastModified < oldestEpubLastModified) {
+        oldestEpubLastModified = epubLastModified
+      }
+    }
+  }
+
+  if (staleFiles.length > 0) {
+    const staleDuration = formatDuration(siteLastModified - oldestEpubLastModified)
+    const staleNames = staleFiles.map((p) => path.basename(p))
+    const fileList = staleNames.join(', ')
+    return {
+      ok: false,
+      level: 'warn',
+      message: `${fileList} is ${staleDuration} older than _site`,
+      remediation: `Your EPUB may not reflect recent build changes.
+    • Run "quire epub" to regenerate the EPUB
+    • Or delete the old EPUB files and run "quire epub"`,
+      docsUrl: `${DOCS_BASE_URL}/quire-commands/#epub`,
+    }
+  }
+
+  // All EPUBs are up to date
+  const fileList = existingNames.join(', ')
+  return {
+    ok: true,
+    message: `${fileList} up to date`,
+  }
+}
+
+export default checkEpubOutput

package/src/lib/doctor/checks/outputs/epub-output.test.js

@@ -0,0 +1,277 @@
+import test from 'ava'
+import sinon from 'sinon'
+import esmock from 'esmock'
+
+const TWO_MINUTES = 120000
+const TEN_MINUTES = 600000
+const ONE_HOUR = 3600000
+const TWO_HOURS = 7200000
+
+const configMock = { default: { get: () => 'HOURLY' } }
+const buildStatusMock = { getStatus: () => undefined }
+
+test.beforeEach((t) => {
+  t.context.sandbox = sinon.createSandbox()
+})
+
+test.afterEach.always((t) => {
+  t.context.sandbox.restore()
+})
+
+test('checkEpubOutput returns N/A when no EPUB files exist', async (t) => {
+  const { sandbox } = t.context
+
+  const { checkEpubOutput } = await esmock('./epub-output.js', {
+    'node:fs': {
+      existsSync: sandbox.stub().returns(false),
+    },
+    '#lib/project/output-paths.js': {
+      getEpubOutputPaths: () => ['epubjs.epub', 'pandoc.epub'],
+    },
+    '#lib/conf/config.js': configMock,
+    '#lib/conf/build-status.js': buildStatusMock,
+  })
+
+  const result = checkEpubOutput()
+
+  t.true(result.ok)
+  t.is(result.level, 'na', 'should return N/A level when no EPUB output')
+  t.regex(result.message, /No EPUB output found/)
+})
+
+test('checkEpubOutput includes remediation when no output found', async (t) => {
+  const { sandbox } = t.context
+
+  const { checkEpubOutput } = await esmock('./epub-output.js', {
+    'node:fs': {
+      existsSync: sandbox.stub().returns(false),
+    },
+    '#lib/project/output-paths.js': {
+      getEpubOutputPaths: () => ['epubjs.epub', 'pandoc.epub'],
+    },
+    '#lib/conf/config.js': configMock,
+    '#lib/conf/build-status.js': buildStatusMock,
+  })
+
+  const result = checkEpubOutput()
+
+  t.truthy(result.remediation)
+  t.regex(result.remediation, /quire epub/)
+  t.regex(result.remediation, /failed/)
+  t.truthy(result.docsUrl)
+})
+
+test('checkEpubOutput returns failure when last EPUB generation failed and no output exists', async (t) => {
+  const { sandbox } = t.context
+
+  const { checkEpubOutput } = await esmock('./epub-output.js', {
+    'node:fs': {
+      existsSync: sandbox.stub().returns(false),
+    },
+    '#lib/project/output-paths.js': {
+      getEpubOutputPaths: () => ['epubjs.epub', 'pandoc.epub'],
+    },
+    '#lib/conf/config.js': configMock,
+    '#lib/conf/build-status.js': {
+      getStatus: () => ({ status: 'failed', timestamp: Date.now() }),
+    },
+  })
+
+  const result = checkEpubOutput()
+
+  t.false(result.ok)
+  t.is(result.level, undefined)
+  t.regex(result.message, /Last EPUB generation failed/)
+  t.truthy(result.remediation)
+  t.regex(result.remediation, /quire epub --debug/)
+  t.truthy(result.docsUrl)
+})
+
+test('checkEpubOutput returns ok when .epub exists but no _site', async (t) => {
+  const { sandbox } = t.context
+
+  const existsSync = sandbox.stub()
+  existsSync.withArgs('epubjs.epub').returns(true)
+  existsSync.withArgs('pandoc.epub').returns(false)
+  existsSync.withArgs('_site').returns(false)
+
+  const { checkEpubOutput } = await esmock('./epub-output.js', {
+    'node:fs': {
+      existsSync,
+    },
+    '#lib/project/output-paths.js': {
+      getEpubOutputPaths: () => ['epubjs.epub', 'pandoc.epub'],
+    },
+    '#lib/conf/config.js': configMock,
+  })
+
+  const result = checkEpubOutput()
+
+  t.true(result.ok)
+  t.regex(result.message, /epubjs\.epub exists/)
+  t.regex(result.message, /no _site to compare/)
+})
+
+test('checkEpubOutput returns ok when .epub is up to date', async (t) => {
+  const { sandbox } = t.context
+
+  const now = Date.now()
+  const epubTime = now // EPUB is current
+  const siteTime = now - TEN_MINUTES // _site is older
+
+  const existsSync = sandbox.stub()
+  existsSync.withArgs('epubjs.epub').returns(true)
+  existsSync.withArgs('pandoc.epub').returns(false)
+  existsSync.withArgs('_site').returns(true)
+
+  const statSync = sandbox.stub()
+  statSync.withArgs('_site').returns({ mtimeMs: siteTime })
+  statSync.withArgs('epubjs.epub').returns({ mtimeMs: epubTime })
+
+  const { checkEpubOutput } = await esmock('./epub-output.js', {
+    'node:fs': {
+      existsSync,
+      statSync,
+    },
+    '#lib/project/output-paths.js': {
+      getEpubOutputPaths: () => ['epubjs.epub', 'pandoc.epub'],
+    },
+    '#lib/conf/config.js': configMock,
+  })
+
+  const result = checkEpubOutput()
+
+  t.true(result.ok)
+  t.regex(result.message, /epubjs\.epub up to date/)
+})
+
+test('checkEpubOutput returns warning when .epub is stale beyond threshold', async (t) => {
+  const { sandbox } = t.context
+
+  const epubTime = Date.now() - TWO_HOURS // 2 hours ago
+  const siteTime = Date.now() // now
+
+  const existsSync = sandbox.stub()
+  existsSync.withArgs('epubjs.epub').returns(true)
+  existsSync.withArgs('pandoc.epub').returns(false)
+  existsSync.withArgs('_site').returns(true)
+
+  const statSync = sandbox.stub()
+  statSync.withArgs('_site').returns({ mtimeMs: siteTime })
+  statSync.withArgs('epubjs.epub').returns({ mtimeMs: epubTime })
+
+  const { checkEpubOutput } = await esmock('./epub-output.js', {
+    'node:fs': {
+      existsSync,
+      statSync,
+    },
+    '#lib/project/output-paths.js': {
+      getEpubOutputPaths: () => ['epubjs.epub', 'pandoc.epub'],
+    },
+    '#lib/conf/config.js': configMock,
+  })
+
+  const result = checkEpubOutput()
+
+  t.false(result.ok)
+  t.is(result.level, 'warn')
+  t.regex(result.message, /epubjs\.epub/)
+  t.regex(result.message, /older than _site/)
+  t.truthy(result.remediation)
+  t.truthy(result.docsUrl)
+})
+
+test('checkEpubOutput returns ok when .epub is stale but within threshold', async (t) => {
+  const { sandbox } = t.context
+
+  const epubTime = Date.now() - TWO_MINUTES // 2 minutes ago
+  const siteTime = Date.now()
+
+  const existsSync = sandbox.stub()
+  existsSync.withArgs('epubjs.epub').returns(true)
+  existsSync.withArgs('pandoc.epub').returns(false)
+  existsSync.withArgs('_site').returns(true)
+
+  const statSync = sandbox.stub()
+  statSync.withArgs('_site').returns({ mtimeMs: siteTime })
+  statSync.withArgs('epubjs.epub').returns({ mtimeMs: epubTime })
+
+  const { checkEpubOutput } = await esmock('./epub-output.js', {
+    'node:fs': {
+      existsSync,
+      statSync,
+    },
+    '#lib/project/output-paths.js': {
+      getEpubOutputPaths: () => ['epubjs.epub', 'pandoc.epub'],
+    },
+    '#lib/conf/config.js': configMock,
+  })
+
+  const result = checkEpubOutput()
+
+  t.true(result.ok)
+  t.regex(result.message, /epubjs\.epub up to date/)
+})
+
+test('checkEpubOutput includes remediation with epub command', async (t) => {
+  const { sandbox } = t.context
+
+  const epubTime = Date.now() - TWO_HOURS
+  const siteTime = Date.now()
+
+  const existsSync = sandbox.stub()
+  existsSync.withArgs('epubjs.epub').returns(true)
+  existsSync.withArgs('pandoc.epub').returns(false)
+  existsSync.withArgs('_site').returns(true)
+
+  const statSync = sandbox.stub()
+  statSync.withArgs('_site').returns({ mtimeMs: siteTime })
+  statSync.withArgs('epubjs.epub').returns({ mtimeMs: epubTime })
+
+  const { checkEpubOutput } = await esmock('./epub-output.js', {
+    'node:fs': {
+      existsSync,
+      statSync,
+    },
+    '#lib/project/output-paths.js': {
+      getEpubOutputPaths: () => ['epubjs.epub', 'pandoc.epub'],
+    },
+    '#lib/conf/config.js': configMock,
+  })
+
+  const result = checkEpubOutput()
+
+  t.false(result.ok)
+  t.regex(result.remediation, /quire epub/)
+})
+
+test('checkEpubOutput uses correct docsUrl', async (t) => {
+  const { sandbox } = t.context
+
+  const epubTime = Date.now() - TWO_HOURS
+  const siteTime = Date.now()
+
+  const existsSync = sandbox.stub()
+  existsSync.withArgs('epubjs.epub').returns(true)
+  existsSync.withArgs('pandoc.epub').returns(false)
+  existsSync.withArgs('_site').returns(true)
+
+  const statSync = sandbox.stub()
+  statSync.withArgs('_site').returns({ mtimeMs: siteTime })
+  statSync.withArgs('epubjs.epub').returns({ mtimeMs: epubTime })
+
+  const { checkEpubOutput } = await esmock('./epub-output.js', {
+    'node:fs': {
+      existsSync,
+      statSync,
+    },
+    '#lib/project/output-paths.js': {
+      getEpubOutputPaths: () => ['epubjs.epub', 'pandoc.epub'],
+    },
+    '#lib/conf/config.js': configMock,
+  })
+
+  const result = checkEpubOutput()
+
+  t.regex(result.docsUrl, /epub/)
+})

package/src/lib/doctor/checks/outputs/index.js

@@ -0,0 +1,10 @@
+/**
+ * Outputs checks
+ *
+ * Checks for build outputs and artifacts.
+ *
+ * @module lib/doctor/checks/outputs
+ */
+export { checkStaleBuild } from './stale-build.js'
+export { checkPdfOutput } from './pdf-output.js'
+export { checkEpubOutput } from './epub-output.js'