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

package/src/lib/project/version.test.js

@@ -0,0 +1,350 @@
+import test from 'ava'
+import { Volume, createFsFromVolume } from 'memfs'
+import esmock from 'esmock'
+
+test.beforeEach((t) => {
+  // Create in-memory file system
+  t.context.vol = new Volume()
+  t.context.fs = createFsFromVolume(t.context.vol)
+})
+
+test.afterEach.always((t) => {
+  // Clear in-memory file system
+  t.context.vol.reset()
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// getVersion tests
+// ─────────────────────────────────────────────────────────────────────────────
+
+test('getVersion should read version from project version file', async (t) => {
+  const { fs, vol } = t.context
+
+  vol.fromJSON({
+    '/project/.quire': '1.0.0'
+  })
+
+  const { getVersion } = await esmock('./version.js', {
+    'fs-extra': {
+      existsSync: (p) => fs.existsSync(p),
+      readFileSync: (p, opts) => fs.readFileSync(p, opts)
+    },
+    './paths.js': {
+      default: { getProjectRoot: () => '/project' }
+    },
+    '#lib/conf/config.js': {
+      default: { get: (key) => key === 'versionFile' ? '.quire' : null }
+    }
+  })
+
+  const result = getVersion('/project')
+
+  t.is(result, '1.0.0', 'should return version string')
+})
+
+test('getVersion should use default project root when not provided', async (t) => {
+  const { fs, vol } = t.context
+
+  vol.fromJSON({
+    '/default/project/.quire': '2.0.0'
+  })
+
+  const { getVersion } = await esmock('./version.js', {
+    'fs-extra': {
+      existsSync: (p) => fs.existsSync(p),
+      readFileSync: (p, opts) => fs.readFileSync(p, opts)
+    },
+    './paths.js': {
+      default: { getProjectRoot: () => '/default/project' }
+    },
+    '#lib/conf/config.js': {
+      default: { get: (key) => key === 'versionFile' ? '.quire' : null }
+    }
+  })
+
+  const result = getVersion()
+
+  t.is(result, '2.0.0', 'should use default project root')
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// setVersion tests
+// ─────────────────────────────────────────────────────────────────────────────
+
+test('setVersion should create version file with quire11ty field', async (t) => {
+  const { fs, vol } = t.context
+
+  vol.fromJSON({
+    '/project/.gitkeep': ''
+  })
+
+  const { setVersion } = await esmock('./version.js', {
+    'fs-extra': {
+      existsSync: (p) => fs.existsSync(p),
+      readFileSync: (p, opts) => fs.readFileSync(p, opts),
+      writeFileSync: (p, data) => fs.writeFileSync(p, data)
+    },
+    './paths.js': {
+      default: { getProjectRoot: () => '/project' }
+    },
+    '#lib/conf/config.js': {
+      default: { get: (key) => key === 'versionFile' ? '.quire' : null }
+    }
+  })
+
+  setVersion('1.5.0', '/project')
+
+  const written = fs.readFileSync('/project/.quire', 'utf8')
+  const parsed = JSON.parse(written)
+
+  t.is(parsed.quire11ty, '1.5.0', 'should write version to quire11ty field')
+})
+
+test('setVersion should preserve existing version file metadata', async (t) => {
+  const { fs, vol } = t.context
+
+  const existingData = JSON.stringify({
+    cli: '1.0.0',
+    starter: 'https://example.com/starter@1.0.0',
+    quire11ty: '1.0.0'
+  })
+
+  vol.fromJSON({
+    '/project/.quire': existingData
+  })
+
+  const { setVersion } = await esmock('./version.js', {
+    'fs-extra': {
+      existsSync: (p) => fs.existsSync(p),
+      readFileSync: (p, opts) => fs.readFileSync(p, opts),
+      writeFileSync: (p, data) => fs.writeFileSync(p, data)
+    },
+    './paths.js': {
+      default: { getProjectRoot: () => '/project' }
+    },
+    '#lib/conf/config.js': {
+      default: { get: (key) => key === 'versionFile' ? '.quire' : null }
+    }
+  })
+
+  setVersion('2.0.0', '/project')
+
+  const written = fs.readFileSync('/project/.quire', 'utf8')
+  const parsed = JSON.parse(written)
+
+  t.is(parsed.quire11ty, '2.0.0', 'should update quire11ty version')
+  t.is(parsed.cli, '1.0.0', 'should preserve cli version')
+  t.is(parsed.starter, 'https://example.com/starter@1.0.0', 'should preserve starter info')
+})
+
+test('setVersion should handle legacy plain text version file', async (t) => {
+  const { fs, vol } = t.context
+
+  // Legacy format: just a version string, not JSON
+  vol.fromJSON({
+    '/project/.quire': '1.0.0-legacy'
+  })
+
+  const { setVersion } = await esmock('./version.js', {
+    'fs-extra': {
+      existsSync: (p) => fs.existsSync(p),
+      readFileSync: (p, opts) => fs.readFileSync(p, opts),
+      writeFileSync: (p, data) => fs.writeFileSync(p, data)
+    },
+    './paths.js': {
+      default: { getProjectRoot: () => '/project' }
+    },
+    '#lib/conf/config.js': {
+      default: { get: (key) => key === 'versionFile' ? '.quire' : null }
+    }
+  })
+
+  setVersion('2.0.0', '/project')
+
+  const written = fs.readFileSync('/project/.quire', 'utf8')
+  const parsed = JSON.parse(written)
+
+  t.is(parsed.quire11ty, '2.0.0', 'should migrate to new JSON format')
+})
+
+test('setVersion should use default project root when not provided', async (t) => {
+  const { fs, vol } = t.context
+
+  vol.fromJSON({
+    '/default/project/.gitkeep': ''
+  })
+
+  const { setVersion } = await esmock('./version.js', {
+    'fs-extra': {
+      existsSync: (p) => fs.existsSync(p),
+      readFileSync: (p, opts) => fs.readFileSync(p, opts),
+      writeFileSync: (p, data) => fs.writeFileSync(p, data)
+    },
+    './paths.js': {
+      default: { getProjectRoot: () => '/default/project' }
+    },
+    '#lib/conf/config.js': {
+      default: { get: (key) => key === 'versionFile' ? '.quire' : null }
+    }
+  })
+
+  setVersion('3.0.0')
+
+  const written = fs.readFileSync('/default/project/.quire', 'utf8')
+  const parsed = JSON.parse(written)
+
+  t.is(parsed.quire11ty, '3.0.0', 'should use default project root')
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// getVersionsFromStarter tests
+// ─────────────────────────────────────────────────────────────────────────────
+
+test('getVersionsFromStarter should read versions from package.json', async (t) => {
+  const { fs, vol } = t.context
+
+  const packageJson = JSON.stringify({
+    name: 'quire-starter-default',
+    version: '1.2.3',
+    peerDependencies: {
+      '@thegetty/quire-11ty': '^1.0.0'
+    }
+  })
+
+  vol.fromJSON({
+    '/project/package.json': packageJson
+  })
+
+  const { getVersionsFromStarter } = await esmock('./version.js', {
+    'fs-extra': {
+      existsSync: (p) => fs.existsSync(p),
+      readFileSync: (p, opts) => fs.readFileSync(p, opts)
+    },
+    './paths.js': {
+      default: { getProjectRoot: () => '/project' }
+    },
+    '#lib/conf/config.js': {
+      default: { get: () => '.quire' }
+    }
+  })
+
+  const result = await getVersionsFromStarter('/project')
+
+  t.is(result.quire11tyVersion, '^1.0.0', 'should return quire-11ty version range')
+  t.is(result.starterVersion, '1.2.3', 'should return starter version')
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// writeVersionFile tests
+// ─────────────────────────────────────────────────────────────────────────────
+
+test('writeVersionFile should write JSON to version file', async (t) => {
+  const { fs, vol } = t.context
+
+  vol.fromJSON({
+    '/project/.gitkeep': ''
+  })
+
+  const { writeVersionFile } = await esmock('./version.js', {
+    'fs-extra': {
+      existsSync: (p) => fs.existsSync(p),
+      readFileSync: (p, opts) => fs.readFileSync(p, opts),
+      writeFileSync: (p, data) => fs.writeFileSync(p, data)
+    },
+    './paths.js': {
+      default: { getProjectRoot: () => '/project' }
+    },
+    '#lib/conf/config.js': {
+      default: { get: (key) => key === 'versionFile' ? '.quire' : null }
+    }
+  })
+
+  const versionInfo = { cli: '1.0.0', starter: 'test@1.0.0' }
+  writeVersionFile('/project', versionInfo)
+
+  const written = fs.readFileSync('/project/.quire', 'utf8')
+  const parsed = JSON.parse(written)
+
+  t.deepEqual(parsed, versionInfo, 'should write version info as JSON')
+})
+
+// ─────────────────────────────────────────────────────────────────────────────
+// readVersionFile tests
+// ─────────────────────────────────────────────────────────────────────────────
+
+test('readVersionFile should return null when file does not exist', async (t) => {
+  const { fs, vol } = t.context
+
+  vol.fromJSON({
+    '/project/.gitkeep': ''
+  })
+
+  const { readVersionFile } = await esmock('./version.js', {
+    'fs-extra': {
+      existsSync: (p) => fs.existsSync(p),
+      readFileSync: (p, opts) => fs.readFileSync(p, opts)
+    },
+    './paths.js': {
+      default: { getProjectRoot: () => '/project' }
+    },
+    '#lib/conf/config.js': {
+      default: { get: (key) => key === 'versionFile' ? '.quire' : null }
+    }
+  })
+
+  const result = readVersionFile('/project')
+
+  t.is(result, null, 'should return null when file does not exist')
+})
+
+test('readVersionFile should parse JSON version file', async (t) => {
+  const { fs, vol } = t.context
+
+  const versionInfo = { cli: '1.0.0', quire11ty: '1.5.0' }
+  vol.fromJSON({
+    '/project/.quire': JSON.stringify(versionInfo)
+  })
+
+  const { readVersionFile } = await esmock('./version.js', {
+    'fs-extra': {
+      existsSync: (p) => fs.existsSync(p),
+      readFileSync: (p, opts) => fs.readFileSync(p, opts)
+    },
+    './paths.js': {
+      default: { getProjectRoot: () => '/project' }
+    },
+    '#lib/conf/config.js': {
+      default: { get: (key) => key === 'versionFile' ? '.quire' : null }
+    }
+  })
+
+  const result = readVersionFile('/project')
+
+  t.deepEqual(result, versionInfo, 'should parse and return version info')
+})
+
+test('readVersionFile should handle legacy plain text format', async (t) => {
+  const { fs, vol } = t.context
+
+  // Legacy format: plain version string
+  vol.fromJSON({
+    '/project/.quire': '1.0.0-legacy'
+  })
+
+  const { readVersionFile } = await esmock('./version.js', {
+    'fs-extra': {
+      existsSync: (p) => fs.existsSync(p),
+      readFileSync: (p, opts) => fs.readFileSync(p, opts)
+    },
+    './paths.js': {
+      default: { getProjectRoot: () => '/project' }
+    },
+    '#lib/conf/config.js': {
+      default: { get: (key) => key === 'versionFile' ? '.quire' : null }
+    }
+  })
+
+  const result = readVersionFile('/project')
+
+  t.deepEqual(result, { version: '1.0.0-legacy' }, 'should return legacy format as object')
+})

package/src/lib/reporter/README.md

@@ -1,3 +1,212 @@
-## CLI Reporter Module
+# Reporter Module
 
-Th `Reporter` module implements a logging concern for the Quire CLI, collecting output from commands and managing render of messages to the console.
+The Reporter module provides CLI progress feedback through spinners and status indicators.
+
+## Overview
+
+This module wraps [ora](https://github.com/sindresorhus/ora) to provide:
+
+- Consistent progress indicators across all CLI commands
+- Automatic suppression in quiet mode, JSON mode, and non-TTY environments
+- Elapsed time display for long-running operations
+- Multi-phase operation support
+
+## Usage
+
+### Basic Usage
+
+```javascript
+import reporter from '#lib/reporter/index.js'
+
+// Start a spinner
+reporter.start('Building site...')
+
+// Do work...
+await build()
+
+// Mark as complete
+reporter.succeed('Build complete')
+```
+
+### Multi-Phase Operations
+
+```javascript
+reporter.start('Cloning starter project...')
+await git.clone(starter, '.')
+
+reporter.update('Initializing repository...')
+await git.init()
+
+reporter.update('Installing dependencies...')
+await npm.install()
+
+reporter.succeed('Project created')
+```
+
+### Error Handling
+
+```javascript
+reporter.start('Generating PDF...')
+try {
+  await generatePdf()
+  reporter.succeed('PDF generated')
+} catch (error) {
+  reporter.fail('PDF generation failed')
+  throw error
+}
+```
+
+### Elapsed Time Display
+
+For operations with unpredictable duration:
+
+```javascript
+reporter.start('Building site...', { showElapsed: true })
+// Shows: ⠋ Building site... (12s)
+await build()
+reporter.succeed('Build complete')
+```
+
+### Configuration
+
+Configure the reporter to respect command options:
+
+```javascript
+async action(options) {
+  // Call at start of action() to respect --quiet, --json flags
+  reporter.configure(options)
+
+  reporter.start('Working...')
+  // ...
+}
+```
+
+| Option | Effect |
+|--------|--------|
+| `quiet: true` | Suppress all spinner output |
+| `json: true` | Suppress spinner (JSON-only output) |
+| `verbose: true` | (Reserved for future use) |
+
+## API Reference
+
+### `reporter.configure(options)`
+
+Configure reporter for current command context.
+
+```javascript
+reporter.configure({ quiet: true, json: false })
+```
+
+### `reporter.start(text, options)`
+
+Start a new spinner.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `text` | `string` | Spinner text |
+| `options.showElapsed` | `boolean` | Show elapsed time (default: `false`) |
+
+### `reporter.update(text)`
+
+Update spinner text while running.
+
+### `reporter.succeed(text)`
+
+Mark operation as successful. Uses current text if `text` not provided.
+
+### `reporter.fail(text)`
+
+Mark operation as failed.
+
+### `reporter.warn(text)`
+
+Mark operation with a warning.
+
+### `reporter.info(text)`
+
+Display an info message.
+
+### `reporter.stop()`
+
+Stop spinner without status indicator.
+
+### `reporter.isSpinning()`
+
+Returns `true` if a spinner is currently running.
+
+### `reporter.getElapsed()`
+
+Returns elapsed time in milliseconds since `start()`, or `null` if not started.
+
+### `reporter.reset()`
+
+Reset all reporter state. Useful in tests.
+
+## Testing
+
+### Mocking in Tests
+
+```javascript
+import esmock from 'esmock'
+import sinon from 'sinon'
+
+const mockReporter = {
+  start: sinon.stub().returnsThis(),
+  update: sinon.stub().returnsThis(),
+  succeed: sinon.stub().returnsThis(),
+  fail: sinon.stub().returnsThis(),
+  configure: sinon.stub().returnsThis(),
+}
+
+const MyCommand = await esmock('./mycommand.js', {
+  '#lib/reporter/index.js': { default: mockReporter }
+})
+```
+
+### Verifying Calls
+
+```javascript
+test('shows progress during build', async (t) => {
+  await command.action(options)
+
+  t.true(mockReporter.start.calledWith('Building...'))
+  t.true(mockReporter.succeed.calledWith('Build complete'))
+})
+```
+
+## Design Decisions
+
+### Why ora?
+
+Automatic supression of output when the `--quiet` or `--json` flags are set or TTY is detected support the four primary user-groups/use-cases: non-technical, developer, maintainer, and programmatic use.
+
+
+| Factor | ora | Alternatives |
+|--------|-----|--------------|
+| Bundle size | 30.4 kB | cli-progress: 62.2 kB |
+| Maintenance | Active | progress: 7 years dormant |
+| Complexity | Simple | listr2: over-engineered |
+
+### Singleton Pattern
+
+Follows the established pattern from `lib/logger`, `lib/git`, and `lib/npm`:
+
+```javascript
+// Singleton export
+export default new Reporter()
+
+// Class export for testing
+export { Reporter }
+```
+
+### Automatic TTY Detection
+
+Spinners are automatically suppressed when:
+
+1. `--quiet` flag is set
+2. `--json` flag is set
+3. `process.stdout.isTTY` is `false` (CI environments, piped output)
+
+## Related
+
+- [lib/logger](../logger/) - Logging abstraction (different concern)