Throw when values are updated in CI

.github/workflows/ci.yml

@@ -23,3 +23,6 @@ jobs:
 
       - name: Build
         run: npm run build
+
+      - name: Check Markdown Docs
+        run: npm run markdown-inject

README.md

@@ -53,6 +53,8 @@ Options:
   -b, --block-prefix <prefix>     specifies the prefix for START and END HTML
                                   comment blocks (default: "CODEBLOCK")
   -n, --no-follow-symbolic-links  prevents globs from following symlinks
+  -f --force-write                write blocks when CI is truthy (default:
+                                  false)
   -q, --quiet                     emits no console log statements (default:
                                   false)
   -e, --no-system-environment     prevents "command"s from receiving system
@@ -235,6 +237,8 @@ My password is:
 
 <!-- CODEBLOCK_END_EXAMPLE_MAP_ENV -->
 
+Calling `markdown-inject` with a truthy `$CI` environment variable will exit with code `1` without writing any changes if any blocks would have been modified. If you instead would intentionally like to write content in a CI environment, this can be bypassed with the [`--force-write` CLI flag](#usage).
+
 ## Codeblock Configuration
 
 The `CODEBLOCK_START` HTML comment config block has the following properties:

package.json

@@ -16,7 +16,7 @@
     "clean": "rm -rf dist",
     "lint": "eslint .",
     "test": "jest",
-    "prepare": "husky install",
+    "prepare": "husky install && ( [ \"$CI\" = 'true' ] || npm run build )",
     "validate": "npm run lint && npm test && npm run build",
     "markdown-inject": "node dist './**/*.md'"
   },

src/__tests__/md-inject.test.ts

@@ -38,8 +38,14 @@ describe('Markdown injection', () => {
     jest.mock('../Logger')
     logger = new Logger()
     Logger.mockImplementation(() => logger)
+    delete process.env.CI
+  })
 
-    process.env = originalProcessEnv
+  afterEach(() => {
+    process.exitCode = 0
+    process.env = {
+      ...originalProcessEnv,
+    }
   })
 
   it('collects all in-repo markdown files', async () => {
@@ -292,6 +298,116 @@ console.log('baz')
     expect(fs.writeFile).toHaveBeenCalledWith('foo.md', outFile)
   })
 
+  it.each([[true], ['true'], ['something'], ['yes']])(
+    'throws gracefully when a change would be written in CI',
+    async (CI) => {
+      process.env.CI = CI as string
+      mock({
+        config: {
+          type: 'file',
+          value: 'bar.js',
+        },
+        mockResponse: `console.log('baz')`,
+      })
+
+      await injectMarkdown()
+
+      expect(process.exitCode).toBe(1)
+    }
+  )
+
+  it.each([[true], ['true'], ['something'], ['yes']])(
+    'does not write when a change would be written in CI',
+    async (CI) => {
+      process.env.CI = CI as string
+      mock({
+        config: {
+          type: 'file',
+          value: 'bar.js',
+        },
+        mockResponse: `console.log('baz')`,
+      })
+
+      await injectMarkdown()
+
+      expect(fs.writeFile).not.toHaveBeenCalled()
+    }
+  )
+
+  it.each([[true], ['true'], ['something'], ['yes']])(
+    'writes file changes and does not throw in CI when --force-write is passed',
+    async (CI) => {
+      process.env.CI = CI as string
+      mock({
+        config: {
+          type: 'file',
+          value: 'bar.js',
+        },
+        mockResponse: `console.log('baz')`,
+      })
+
+      await injectMarkdown({
+        forceWrite: true,
+
+        // defaults
+        blockPrefix: 'CODEBLOCK',
+        followSymbolicLinks: true,
+        globPattern: '**/*.md',
+        quiet: false,
+      })
+
+      const outFile = `
+<!-- CODEBLOCK_START {"type":"file","value":"bar.js"} -->
+<!-- prettier-ignore -->
+~~~~~~~~~~js
+File: bar.js
+
+console.log('baz')
+~~~~~~~~~~
+
+<!-- CODEBLOCK_END -->`
+      expect(fs.writeFile).toHaveBeenCalledWith('foo.md', outFile)
+      expect(process.exitCode).not.toBe(1)
+    }
+  )
+
+  it.each([[''], ['false'], [false], [undefined]])(
+    'does not throw when CI is %s',
+    async (CI) => {
+      process.env.CI = CI as string
+      mock({
+        config: {
+          type: 'file',
+          value: 'bar.js',
+        },
+        mockResponse: `console.log('baz')`,
+      })
+
+      await injectMarkdown({
+        forceWrite: true,
+
+        // defaults
+        blockPrefix: 'CODEBLOCK',
+        followSymbolicLinks: true,
+        globPattern: '**/*.md',
+        quiet: false,
+      })
+
+      const outFile = `
+<!-- CODEBLOCK_START {"type":"file","value":"bar.js"} -->
+<!-- prettier-ignore -->
+~~~~~~~~~~js
+File: bar.js
+
+console.log('baz')
+~~~~~~~~~~
+
+<!-- CODEBLOCK_END -->`
+      expect(fs.writeFile).toHaveBeenCalledWith('foo.md', outFile)
+      expect(process.exitCode).not.toBe(1)
+    }
+  )
+
   it('trims whitespace (command)', async () => {
     mock({
       config: {

src/index.ts

@@ -19,6 +19,7 @@ program
     '-n, --no-follow-symbolic-links',
     'prevents globs from following symlinks'
   )
+  .option('-f --force-write', 'write blocks when CI is truthy', false)
   .option('-q, --quiet', 'emits no console log statements', false)
   .option(
     '-e, --no-system-environment',
@@ -40,6 +41,7 @@ Examples:
     await injectMarkdown({
       blockPrefix: options.blockPrefix,
       followSymbolicLinks: options.followSymbolicLinks,
+      forceWrite: options.forceWrite,
       globPattern,
       quiet: options.quiet,
       useSystemEnvironment: options.systemEnvironment,

src/md-inject.ts

@@ -3,6 +3,7 @@ import fs from 'fs-extra'
 import path from 'path'
 import { exec } from 'child_process'
 import Logger from './Logger'
+import { isCI } from './utils'
 
 enum BlockSourceType {
   file = 'file',
@@ -26,6 +27,7 @@ interface BlockInputOptions extends Omit<BlockOptions, 'type'> {
 interface ReplaceOptions {
   blockPrefix: string
   followSymbolicLinks: boolean
+  forceWrite: boolean
   globPattern: string
   quiet: boolean
   useSystemEnvironment: boolean
@@ -35,19 +37,27 @@ const main = async (
   {
     blockPrefix,
     followSymbolicLinks,
+    forceWrite,
     globPattern,
     quiet,
     useSystemEnvironment,
   }: ReplaceOptions = {
     blockPrefix: 'CODEBLOCK',
     followSymbolicLinks: true,
+    forceWrite: false,
     globPattern: '**/*.md',
     quiet: false,
     useSystemEnvironment: true,
   }
 ): Promise<void> => {
   const logger = new Logger(quiet)
-  logger.group('Injecting Markdown Blocks')
+
+  const writeChangedBlocks = forceWrite || !isCI()
+  logger.group(
+    writeChangedBlocks
+      ? 'Injecting Markdown Blocks'
+      : 'Checking Markdown Blocks'
+  )
 
   const markdownFiles = await glob(globPattern, {
     followSymbolicLinks,
@@ -204,7 +214,9 @@ ${endPragma}`
     }
 
     if (modifiedFileContents !== originalFileContents) {
-      await fs.writeFile(fileName, modifiedFileContents)
+      if (writeChangedBlocks) {
+        await fs.writeFile(fileName, modifiedFileContents)
+      }
       logger.log(
         `${fileName}: ${blocksChanged} of ${totalBlocks} blocks changed (${blocksIgnored} ignored)`
       )
@@ -243,8 +255,19 @@ ${endPragma}`
     logger.log(
       `Total: ${totalChanges} of ${totalBlocks} blocks (${totalIgnored} ignored)`
     )
+
+    if (!writeChangedBlocks && totalChanges !== 0) {
+      logger.log()
+      logger.error(
+        'ERROR: Block updates detected in CI.\nNo block changes were written.\nCall with --force-write to bypass.'
+      )
+      logger.log()
+      process.exitCode = 1
+    }
   } catch (err) {
+    logger.log()
     logger.error(err)
+    logger.log()
     process.exitCode = 1
   }
   logger.groupEnd()

src/utils.ts

@@ -0,0 +1,9 @@
+export const isCI = (): boolean => {
+  const { CI } = process.env
+
+  const falsyValues = [undefined, null, '', false, false.toString()]
+
+  const isNotCi = falsyValues.some((falsyValue) => falsyValue === CI)
+
+  return !isNotCi
+}