feat(cli): add --json output, .md-ignore support, improve error msgs

Author: DavidWells

packages/core/src/cli-run.js

@@ -60,6 +60,18 @@ function interpretEscapes(str) {
   return str.replace(/\\n/g, '\n').replace(/\\t/g, '\t')
 }
 
+/**
+ * JSON.stringify replacer that handles RegExp objects
+ * @param {string} key
+ * @param {any} value
+ */
+function jsonReplacer(key, value) {
+  if (value instanceof RegExp) {
+    return value.toString()
+  }
+  return value
+}
+
 /**
  * Check if string looks like markdown content vs a file path
  * @param {string} str
@@ -103,6 +115,7 @@ Options:
   --output           Output directory
   --open             Opening comment keyword (default: docs)
   --close            Closing comment keyword (default: /docs)
+  --json             Output full result as JSON
   --pretty           Render output with ANSI styling
   --dry              Dry run - show what would be changed
   --debug            Show debug output
@@ -130,7 +143,12 @@ Stdin/stdout mode:
   }
 
   // Check if first positional arg is markdown content (before stdin check)
-  const firstArg = options._ && options._[0]
+  // Handle case where mri assigns content to a flag (e.g., --json '# content')
+  let firstArg = options._ && options._[0]
+  const outputJson = options.json === true || (typeof options.json === 'string' && isMarkdownContent(options.json))
+  if (typeof options.json === 'string' && isMarkdownContent(options.json)) {
+    firstArg = options.json
+  }
   const openKeyword = options.open || 'docs'
   const closeKeyword = options.close || (options.open && options.open !== 'docs' ? `/${options.open}` : '/docs')
   if (firstArg && isMarkdownContent(firstArg)) {
@@ -143,14 +161,12 @@ Stdin/stdout mode:
       transforms: defaultTransforms,
       dryRun: true,
     })
-    // TODO future pretty option
-    // if (options.pretty) {
-    //   console.log(await renderMarkdown(result.updatedContents))
-    // } else {
-    //   console.log()
-    //   console.log(result.updatedContents)
-    // }
-    console.log(result.updatedContents)
+    console.log('result', result)
+    if (outputJson) {
+      console.log(JSON.stringify(result, jsonReplacer, 2))
+    } else {
+      console.log(result.updatedContents)
+    }
     return
   }
 
@@ -168,14 +184,11 @@ Stdin/stdout mode:
         transforms: defaultTransforms,
         dryRun: true, // Don't write files
       })
-      // TODO future pretty option
-      // if (options.pretty) {
-      //   console.log(await renderMarkdown(result.updatedContents))
-      // } else {
-      //   console.log()
-      //   console.log(result.updatedContents)
-      // }
-      console.log(result.updatedContents)
+      if (outputJson) {
+        console.log(JSON.stringify(result, jsonReplacer, 2))
+      } else {
+        console.log(result.updatedContents)
+      }
       return
     }
   }

packages/core/src/index.js

@@ -13,7 +13,7 @@ const remoteTransform = require('./transforms/remote')
 const installTransform = require('./transforms/install')
 const { getSyntaxInfo } = require('./utils/syntax')
 const { onlyUnique, getCodeLocation, pluralize } = require('./utils')
-const { readFile, resolveOutputPath, resolveFlatPath } = require('./utils/fs')
+const { readFile, resolveOutputPath, resolveFlatPath, hasIgnoreFile } = require('./utils/fs')
 const stringBreak = require('./utils/string-break')
 const { processFile } = require('comment-block-replacer')
 const { blockTransformer } = require('comment-block-transformer')
@@ -257,7 +257,10 @@ async function markdownMagic(globOrOpts = {}, options = {}) {
 
   let files = []
   try {
-    files = (await Promise.all(pathsPromise)).flat().filter(onlyUnique)
+    files = (await Promise.all(pathsPromise))
+      .flat()
+      .filter(onlyUnique)
+      .filter((f) => !hasIgnoreFile(f))
     // opts.files = files
   } catch (e) {
     // console.log(e.message)
@@ -541,12 +544,16 @@ async function markdownMagic(globOrOpts = {}, options = {}) {
     let planMsg = `${count} Found ${transformsToRun.length} transforms in ${item.srcPath}`
     planTotal = planTotal + transformsToRun.length
     // logger(`Found ${transformsToRun.length} transforms in ${item.srcPath}`)
+    const maxPrefixLen = Math.max(...transformsToRun.map((t) => {
+      return `"${t.transform}" on line ${t.lines[0]}`.length
+    }))
     transformsToRun.forEach((trn) => {
       const line = trn.lines[0]
+      const prefix = `"${trn.transform}" on line ${line}`
+      const paddedPrefix = prefix.padEnd(maxPrefixLen)
       const location = getCodeLocation(item.srcPath, line)
-      const planData = `      - "${trn.transform}" at line ${line} → ${location}`
+      const planData = `      - ${paddedPrefix}  →  ${location}`
       planMsg += `\n${planData}`
-      // logger(` - "${trn.transform}" at line ${trn.lines[0]}`)
     })
     const newLine = plan.length !== i + 1 ? '\n' : ''
     return `${planMsg}${newLine}`

packages/core/src/transforms/code/index.js

@@ -91,8 +91,9 @@ module.exports = async function CODE(api) {
         if (src === './relative/path/to/code.js') {
           return api.content
         } else {
-          console.log(`FILE NOT FOUND ${codeFilePath}`)
-          throw e
+          const err = new Error(`FILE NOT FOUND: ${codeFilePath}\n  Referenced in: ${srcPath}\n  src="${src}"`)
+          err.code = 'ENOENT'
+          throw err
         }
       }
     }

packages/core/src/transforms/file.js

@@ -23,8 +23,15 @@ module.exports = function FILE(api) {
       if (options.src === './path/to/file') {
         return api.content
       }
-      console.log(`FILE NOT FOUND ${resolvedFilePath}`)
-      throw e
+      const err = new Error(`FILE NOT FOUND: ${resolvedFilePath}
+      
+Referenced in: ${srcPath}
+
+Via the "src" attribute: src="${options.src}"
+
+`)
+      err.code = 'ENOENT'
+      throw err
     }
   }
 

packages/core/src/utils/fs.js

@@ -192,11 +192,34 @@ function isLocalPath(filePath) {
   return _isLocalPath(filePath)
 }
 
+const fsSync = require('fs')
+
+/**
+ * Check if file's directory or any parent has .md-ignore
+ * @param {string} filePath - Absolute path to file
+ * @returns {boolean} True if should be ignored
+ */
+function hasIgnoreFile(filePath) {
+  let dir = dirname(filePath)
+  const root = resolve('/')
+  while (dir !== root) {
+    const ignoreFile = join(dir, '.md-ignore')
+    if (fsSync.existsSync(ignoreFile)) {
+      return true
+    }
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return false
+}
+
 module.exports = {
   isLocalPath,
   writeFile,
-  readFile, 
+  readFile,
   findUp,
+  hasIgnoreFile,
   resolveOutputPath,
   resolveFlatPath,
   resolveCommonParent,