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

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

@@ -0,0 +1,144 @@
+/**
+ * PDF output check
+ *
+ * Checks for PDF output files using the same path resolution logic as the
+ * PDF generation command. Supports both default engine-named paths and
+ * config-aware custom output paths.
+ *
+ * @module lib/doctor/checks/outputs/pdf-output
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import createDebug from '#debug'
+import { getPdfOutputPaths } from '#lib/project/output-paths.js'
+import { loadProjectConfig } from '#lib/project/config.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:pdf-output')
+
+/**
+ * Load pdf config from the project's config.yaml
+ *
+ * Returns undefined if config cannot be loaded (not in a project, missing
+ * config file, no pdf section). The caller falls back to engine defaults.
+ *
+ * @returns {Promise<Object|undefined>}
+ */
+async function loadPdfConfig() {
+  try {
+    const projectConfig = await loadProjectConfig()
+    return projectConfig.pdf
+  } catch {
+    debug('Could not load project config, using engine defaults only')
+    return undefined
+  }
+}
+
+/**
+ * Check if PDF output exists and is up to date with _site
+ *
+ * PDF is generated from _site, so if _site is newer than the PDF,
+ * the PDF is considered stale.
+ *
+ * Loads the project config to resolve config-aware PDF output paths,
+ * matching the same resolution logic as `lib/pdf/index.js`.
+ *
+ * @returns {Promise<import('../../index.js').CheckResult>}
+ */
+export async function checkPdfOutput() {
+  const pdfConfig = await loadPdfConfig()
+
+  // Get all possible PDF paths (config-aware + engine defaults)
+  const candidatePaths = getPdfOutputPaths({ pdfConfig })
+  debug('candidate PDF paths: %o', candidatePaths)
+
+  // Find which PDF files actually exist
+  const existingPdfs = candidatePaths.filter((p) => fs.existsSync(p))
+
+  if (existingPdfs.length === 0) {
+    debug('No PDF files found, checking stored pdf status')
+
+    const status = getStatus(process.cwd(), 'pdf')
+    if (status?.status === 'failed') {
+      debug('Last pdf generation failed (stored status)')
+      return {
+        ok: false,
+        message: 'Last PDF generation failed',
+        remediation: `The last "quire pdf" run failed. Check the output for errors and try again.
+    • Run "quire pdf --debug" for detailed error output`,
+        docsUrl: `${DOCS_BASE_URL}/quire-commands/#pdf`,
+      }
+    }
+
+    return {
+      ok: true,
+      level: 'na',
+      message: 'No PDF output found',
+      remediation: `Run "quire pdf" to generate a PDF.
+    • If you already ran "quire pdf" and it failed, check the output for errors`,
+      docsUrl: `${DOCS_BASE_URL}/quire-commands/#pdf`,
+    }
+  }
+
+  // Use basenames for display
+  const existingNames = existingPdfs.map((p) => path.basename(p))
+  debug('found PDF files: %o', existingNames)
+
+  // Check if _site exists
+  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 PDF for staleness beyond the configured threshold
+  const thresholdMs = resolveStaleThreshold(config.get('staleThreshold'))
+  const staleFiles = []
+  let oldestPdfLastModified = Infinity
+
+  for (const pdfFile of existingPdfs) {
+    const { mtimeMs: pdfLastModified } = fs.statSync(pdfFile)
+    debug('%s lastModified: %d', path.basename(pdfFile), pdfLastModified)
+
+    const staleDelta = siteLastModified - pdfLastModified
+    if (staleDelta > thresholdMs) {
+      staleFiles.push(pdfFile)
+      if (pdfLastModified < oldestPdfLastModified) {
+        oldestPdfLastModified = pdfLastModified
+      }
+    }
+  }
+
+  if (staleFiles.length > 0) {
+    const staleDuration = formatDuration(siteLastModified - oldestPdfLastModified)
+    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 PDF may not reflect recent build changes.
+    • Run "quire pdf" to regenerate the PDF
+    • Or delete the old PDF files and run "quire pdf"`,
+      docsUrl: `${DOCS_BASE_URL}/quire-commands/#pdf`,
+    }
+  }
+
+  // All PDFs are up to date
+  const fileList = existingNames.join(', ')
+  return {
+    ok: true,
+    message: `${fileList} up to date`,
+  }
+}
+
+export default checkPdfOutput

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

@@ -0,0 +1,377 @@
+import test from 'ava'
+import path from 'node:path'
+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('checkPdfOutput returns N/A when no PDF files exist', async (t) => {
+  const { sandbox } = t.context
+
+  const { checkPdfOutput } = await esmock('./pdf-output.js', {
+    'node:fs': {
+      existsSync: sandbox.stub().returns(false),
+    },
+    '#lib/project/output-paths.js': {
+      getPdfOutputPaths: () => ['pagedjs.pdf', 'prince.pdf'],
+    },
+    '#lib/project/config.js': {
+      loadProjectConfig: async () => ({}),
+    },
+    '#lib/conf/config.js': configMock,
+    '#lib/conf/build-status.js': buildStatusMock,
+  })
+
+  const result = await checkPdfOutput()
+
+  t.true(result.ok)
+  t.is(result.level, 'na', 'should return N/A level when no PDF output')
+  t.regex(result.message, /No PDF output found/)
+})
+
+test('checkPdfOutput includes remediation when no output found', async (t) => {
+  const { sandbox } = t.context
+
+  const { checkPdfOutput } = await esmock('./pdf-output.js', {
+    'node:fs': {
+      existsSync: sandbox.stub().returns(false),
+    },
+    '#lib/project/output-paths.js': {
+      getPdfOutputPaths: () => ['pagedjs.pdf', 'prince.pdf'],
+    },
+    '#lib/project/config.js': {
+      loadProjectConfig: async () => ({}),
+    },
+    '#lib/conf/config.js': configMock,
+    '#lib/conf/build-status.js': buildStatusMock,
+  })
+
+  const result = await checkPdfOutput()
+
+  t.truthy(result.remediation)
+  t.regex(result.remediation, /quire pdf/)
+  t.regex(result.remediation, /failed/)
+  t.truthy(result.docsUrl)
+})
+
+test('checkPdfOutput returns failure when last PDF generation failed and no output exists', async (t) => {
+  const { sandbox } = t.context
+
+  const { checkPdfOutput } = await esmock('./pdf-output.js', {
+    'node:fs': {
+      existsSync: sandbox.stub().returns(false),
+    },
+    '#lib/project/output-paths.js': {
+      getPdfOutputPaths: () => ['pagedjs.pdf', 'prince.pdf'],
+    },
+    '#lib/project/config.js': {
+      loadProjectConfig: async () => ({}),
+    },
+    '#lib/conf/config.js': configMock,
+    '#lib/conf/build-status.js': {
+      getStatus: () => ({ status: 'failed', timestamp: Date.now() }),
+    },
+  })
+
+  const result = await checkPdfOutput()
+
+  t.false(result.ok)
+  t.is(result.level, undefined)
+  t.regex(result.message, /Last PDF generation failed/)
+  t.truthy(result.remediation)
+  t.regex(result.remediation, /quire pdf --debug/)
+  t.truthy(result.docsUrl)
+})
+
+test('checkPdfOutput returns ok when PDF exists but no _site', async (t) => {
+  const { sandbox } = t.context
+
+  const existsSync = sandbox.stub()
+  existsSync.withArgs('pagedjs.pdf').returns(true)
+  existsSync.withArgs('prince.pdf').returns(false)
+  existsSync.withArgs('_site').returns(false)
+
+  const { checkPdfOutput } = await esmock('./pdf-output.js', {
+    'node:fs': {
+      existsSync,
+    },
+    '#lib/project/output-paths.js': {
+      getPdfOutputPaths: () => ['pagedjs.pdf', 'prince.pdf'],
+    },
+    '#lib/project/config.js': {
+      loadProjectConfig: async () => ({}),
+    },
+    '#lib/conf/config.js': configMock,
+  })
+
+  const result = await checkPdfOutput()
+
+  t.true(result.ok)
+  t.regex(result.message, /pagedjs\.pdf exists/)
+  t.regex(result.message, /no _site to compare/)
+})
+
+test('checkPdfOutput returns ok when PDF is up to date', async (t) => {
+  const { sandbox } = t.context
+
+  const now = Date.now()
+  const pdfTime = now // PDF is current
+  const siteTime = now - TEN_MINUTES // _site is older
+
+  const existsSync = sandbox.stub()
+  existsSync.withArgs('pagedjs.pdf').returns(true)
+  existsSync.withArgs('prince.pdf').returns(false)
+  existsSync.withArgs('_site').returns(true)
+
+  const statSync = sandbox.stub()
+  statSync.withArgs('_site').returns({ mtimeMs: siteTime })
+  statSync.withArgs('pagedjs.pdf').returns({ mtimeMs: pdfTime })
+
+  const { checkPdfOutput } = await esmock('./pdf-output.js', {
+    'node:fs': {
+      existsSync,
+      statSync,
+    },
+    '#lib/project/output-paths.js': {
+      getPdfOutputPaths: () => ['pagedjs.pdf', 'prince.pdf'],
+    },
+    '#lib/project/config.js': {
+      loadProjectConfig: async () => ({}),
+    },
+    '#lib/conf/config.js': configMock,
+  })
+
+  const result = await checkPdfOutput()
+
+  t.true(result.ok)
+  t.regex(result.message, /pagedjs\.pdf up to date/)
+})
+
+test('checkPdfOutput returns warning when PDF is stale beyond threshold', async (t) => {
+  const { sandbox } = t.context
+
+  const pdfTime = Date.now() - TWO_HOURS // 2 hours ago
+  const siteTime = Date.now() // now
+
+  const existsSync = sandbox.stub()
+  existsSync.withArgs('pagedjs.pdf').returns(true)
+  existsSync.withArgs('prince.pdf').returns(false)
+  existsSync.withArgs('_site').returns(true)
+
+  const statSync = sandbox.stub()
+  statSync.withArgs('_site').returns({ mtimeMs: siteTime })
+  statSync.withArgs('pagedjs.pdf').returns({ mtimeMs: pdfTime })
+
+  const { checkPdfOutput } = await esmock('./pdf-output.js', {
+    'node:fs': {
+      existsSync,
+      statSync,
+    },
+    '#lib/project/output-paths.js': {
+      getPdfOutputPaths: () => ['pagedjs.pdf', 'prince.pdf'],
+    },
+    '#lib/project/config.js': {
+      loadProjectConfig: async () => ({}),
+    },
+    '#lib/conf/config.js': configMock,
+  })
+
+  const result = await checkPdfOutput()
+
+  t.false(result.ok)
+  t.is(result.level, 'warn')
+  t.regex(result.message, /pagedjs\.pdf/)
+  t.regex(result.message, /older than _site/)
+  t.truthy(result.remediation)
+  t.truthy(result.docsUrl)
+})
+
+test('checkPdfOutput returns ok when PDF is stale but within threshold', async (t) => {
+  const { sandbox } = t.context
+
+  const pdfTime = Date.now() - TWO_MINUTES // 2 minutes ago
+  const siteTime = Date.now()
+
+  const existsSync = sandbox.stub()
+  existsSync.withArgs('pagedjs.pdf').returns(true)
+  existsSync.withArgs('prince.pdf').returns(false)
+  existsSync.withArgs('_site').returns(true)
+
+  const statSync = sandbox.stub()
+  statSync.withArgs('_site').returns({ mtimeMs: siteTime })
+  statSync.withArgs('pagedjs.pdf').returns({ mtimeMs: pdfTime })
+
+  const { checkPdfOutput } = await esmock('./pdf-output.js', {
+    'node:fs': {
+      existsSync,
+      statSync,
+    },
+    '#lib/project/output-paths.js': {
+      getPdfOutputPaths: () => ['pagedjs.pdf', 'prince.pdf'],
+    },
+    '#lib/project/config.js': {
+      loadProjectConfig: async () => ({}),
+    },
+    '#lib/conf/config.js': configMock,
+  })
+
+  const result = await checkPdfOutput()
+
+  t.true(result.ok)
+  t.regex(result.message, /pagedjs\.pdf up to date/)
+})
+
+test('checkPdfOutput checks multiple PDF files', async (t) => {
+  const { sandbox } = t.context
+
+  const now = Date.now()
+  const pdfTime = now
+  const siteTime = now - TEN_MINUTES
+
+  const existsSync = sandbox.stub()
+  existsSync.withArgs('pagedjs.pdf').returns(true)
+  existsSync.withArgs('prince.pdf').returns(true)
+  existsSync.withArgs('_site').returns(true)
+
+  const statSync = sandbox.stub()
+  statSync.withArgs('_site').returns({ mtimeMs: siteTime })
+  statSync.withArgs('pagedjs.pdf').returns({ mtimeMs: pdfTime })
+  statSync.withArgs('prince.pdf').returns({ mtimeMs: pdfTime })
+
+  const { checkPdfOutput } = await esmock('./pdf-output.js', {
+    'node:fs': {
+      existsSync,
+      statSync,
+    },
+    '#lib/project/output-paths.js': {
+      getPdfOutputPaths: () => ['pagedjs.pdf', 'prince.pdf'],
+    },
+    '#lib/project/config.js': {
+      loadProjectConfig: async () => ({}),
+    },
+    '#lib/conf/config.js': configMock,
+  })
+
+  const result = await checkPdfOutput()
+
+  t.true(result.ok)
+  t.regex(result.message, /pagedjs\.pdf/)
+  t.regex(result.message, /prince\.pdf/)
+})
+
+test('checkPdfOutput includes remediation with pdf command', async (t) => {
+  const { sandbox } = t.context
+
+  const pdfTime = Date.now() - TWO_HOURS
+  const siteTime = Date.now()
+
+  const existsSync = sandbox.stub()
+  existsSync.withArgs('pagedjs.pdf').returns(true)
+  existsSync.withArgs('prince.pdf').returns(false)
+  existsSync.withArgs('_site').returns(true)
+
+  const statSync = sandbox.stub()
+  statSync.withArgs('_site').returns({ mtimeMs: siteTime })
+  statSync.withArgs('pagedjs.pdf').returns({ mtimeMs: pdfTime })
+
+  const { checkPdfOutput } = await esmock('./pdf-output.js', {
+    'node:fs': {
+      existsSync,
+      statSync,
+    },
+    '#lib/project/output-paths.js': {
+      getPdfOutputPaths: () => ['pagedjs.pdf', 'prince.pdf'],
+    },
+    '#lib/project/config.js': {
+      loadProjectConfig: async () => ({}),
+    },
+    '#lib/conf/config.js': configMock,
+  })
+
+  const result = await checkPdfOutput()
+
+  t.false(result.ok)
+  t.regex(result.remediation, /quire pdf/)
+})
+
+test('checkPdfOutput loads project config to resolve config-aware paths', async (t) => {
+  const { sandbox } = t.context
+
+  const pdfConfig = { outputDir: 'pdf', filename: 'my-publication' }
+  const configPath = path.join('_site', 'pdf', 'my-publication.pdf')
+
+  const existsSync = sandbox.stub().returns(false)
+  existsSync.withArgs(configPath).returns(true)
+  existsSync.withArgs('_site').returns(true)
+
+  const now = Date.now()
+  const statSync = sandbox.stub()
+  statSync.withArgs('_site').returns({ mtimeMs: now - TEN_MINUTES })
+  statSync.withArgs(configPath).returns({ mtimeMs: now })
+
+  const { checkPdfOutput } = await esmock('./pdf-output.js', {
+    'node:fs': {
+      existsSync,
+      statSync,
+    },
+    '#lib/project/output-paths.js': {
+      getPdfOutputPaths: (opts) => {
+        const paths = []
+        if (opts.pdfConfig) {
+          paths.push(configPath)
+        }
+        paths.push('pagedjs.pdf', 'prince.pdf')
+        return paths
+      },
+    },
+    '#lib/project/config.js': {
+      loadProjectConfig: async () => ({ pdf: pdfConfig }),
+    },
+    '#lib/conf/config.js': configMock,
+  })
+
+  const result = await checkPdfOutput()
+
+  t.true(result.ok)
+  t.regex(result.message, /my-publication\.pdf up to date/)
+})
+
+test('checkPdfOutput falls back to engine defaults when config loading fails', async (t) => {
+  const { sandbox } = t.context
+
+  const { checkPdfOutput } = await esmock('./pdf-output.js', {
+    'node:fs': {
+      existsSync: sandbox.stub().returns(false),
+    },
+    '#lib/project/output-paths.js': {
+      getPdfOutputPaths: (opts) => {
+        t.is(opts.pdfConfig, undefined, 'pdfConfig should be undefined when config fails')
+        return ['pagedjs.pdf', 'prince.pdf']
+      },
+    },
+    '#lib/project/config.js': {
+      loadProjectConfig: async () => { throw new Error('No config.yaml') },
+    },
+    '#lib/conf/config.js': configMock,
+    '#lib/conf/build-status.js': buildStatusMock,
+  })
+
+  const result = await checkPdfOutput()
+
+  t.true(result.ok)
+  t.is(result.level, 'na')
+})

package/src/lib/doctor/checks/outputs/stale-build.js

@@ -0,0 +1,122 @@
+/**
+ * Stale build check
+ *
+ * @module lib/doctor/checks/outputs/stale-build
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { SOURCE_DIRECTORIES } from '#lib/project/index.js'
+import config from '#lib/conf/config.js'
+import { getStatus } from '#lib/conf/build-status.js'
+import createDebug from '#debug'
+import { DOCS_BASE_URL, resolveStaleThreshold } from '#lib/doctor/constants.js'
+import { formatDuration } from '#lib/doctor/formatDuration.js'
+
+const debug = createDebug('lib:doctor:stale-build')
+
+/**
+ * Get the latest modification time from files in a directory (recursive)
+ * @param {string} dir - Directory to scan
+ * @returns {number} - Latest modified timestamp in milliseconds, or 0 if directory doesn't exist
+ */
+function getLatestModified(dir) {
+  if (!fs.existsSync(dir)) {
+    return 0
+  }
+
+  let newest = 0
+
+  const scan = (currentDir) => {
+    const entries = fs.readdirSync(currentDir, { withFileTypes: true })
+    for (const entry of entries) {
+      const fullPath = path.join(currentDir, entry.name)
+      try {
+        const { mtimeMs: lastModified } = fs.statSync(fullPath)
+        if (lastModified > newest) {
+          newest = lastModified
+        }
+        if (entry.isDirectory()) {
+          scan(fullPath)
+        }
+      } catch {
+        // Skip files we can't stat (permissions, etc.)
+      }
+    }
+  }
+
+  scan(dir)
+  return newest
+}
+
+/**
+ * Check if build output is stale (source files newer than _site)
+ * @returns {import('../../index.js').CheckResult}
+ */
+export function checkStaleBuild() {
+  const siteDir = '_site'
+
+  // Skip if not in a project or no build output exists
+  if (!fs.existsSync(siteDir)) {
+    debug('No _site directory found, checking stored build status')
+
+    const status = getStatus(process.cwd(), 'build')
+    if (status?.status === 'failed') {
+      debug('Last build failed (stored status)')
+      return {
+        ok: false,
+        message: 'Last build failed',
+        remediation: `The last "quire build" run failed. Check the output for errors and try again.
+    • Run "quire build --debug" for detailed error output`,
+        docsUrl: `${DOCS_BASE_URL}/quire-commands/#preview-and-build`,
+      }
+    }
+
+    return {
+      ok: true,
+      level: 'na',
+      message: 'No build output found',
+      remediation: `Run "quire build" to generate the site.
+    • If you already ran "quire build" and it failed, check the output for errors`,
+      docsUrl: `${DOCS_BASE_URL}/quire-commands/#preview-and-build`,
+    }
+  }
+
+  // Get _site last modified time
+  const { mtimeMs: siteLastModified } = fs.statSync(siteDir)
+  debug('_site lastModified: %d', siteLastModified)
+
+  // Find newest source file across all source directories
+  let newestSourceLastModified = 0
+  for (const dir of SOURCE_DIRECTORIES) {
+    const lastModified = getLatestModified(dir)
+    if (lastModified > newestSourceLastModified) {
+      newestSourceLastModified = lastModified
+    }
+  }
+  debug('Newest source lastModified: %d', newestSourceLastModified)
+
+  // If source is newer than build by more than the stale threshold, warn
+  const thresholdMs = resolveStaleThreshold(config.get('staleThreshold'))
+  const staleDelta = newestSourceLastModified - siteLastModified
+  debug('stale delta: %dms, threshold: %dms (%s)', staleDelta, thresholdMs, config.get('staleThreshold'))
+
+  if (staleDelta > thresholdMs) {
+    const staleDuration = formatDuration(staleDelta)
+    return {
+      ok: false,
+      level: 'warn',
+      message: `Build output is ${staleDuration} older than source files`,
+      remediation: `Your build output may not reflect recent changes.
+    • Run "quire build" to regenerate the site
+    • Or run "quire preview" which auto-rebuilds on changes`,
+      docsUrl: `${DOCS_BASE_URL}/quire-commands/#preview-and-build`,
+    }
+  }
+
+  return {
+    ok: true,
+    message: 'Build output is up to date',
+  }
+}
+
+export default checkStaleBuild