markdown-magic 3.6.5 → 4.0.0

package/src/process-contents.js

@@ -1,461 +1,5 @@
-const { parseBlocks } = require('./block-parser')
-const { deepLog } = require('./utils/logs')
-const { getCodeLocation } = require('./utils')
-const { indentString, trimString } = require('./utils/text')
-const { OPEN_WORD, CLOSE_WORD, SYNTAX } = require('./defaults')
-
-/**
- * Configuration object for processing contents.
- * @typedef {Object} ProcessContentConfig
- * @property {string} srcPath - The source path.
- * @property {string} outputPath - The output path.
- * @property {string} [open=OPEN_WORD] - The opening delimiter.
- * @property {string} [close=CLOSE_WORD] - The closing delimiter.
- * @property {string} [syntax='md'] - The syntax type.
- * @property {Array<Function>} [transforms=[]] - The array of transform functions.
- * @property {Array<Function>} [beforeMiddleware=[]] - The array of middleware functions to be executed before processing.
- * @property {Array<Function>} [afterMiddleware=[]] - The array of middleware functions to be executed after processing.
- * @property {boolean} [debug=false] - Enable debug mode.
- * @property {boolean} [removeComments=false] - Remove comments from the processed contents.
- */
-
-/**
- * Pull comment blocks out of content and process them
- * @param {string} text 
- * @param {ProcessContentConfig} config 
- * @returns 
- */
-async function processContents(text, config) {
-  const opts = config || {}
-
-  const {
-    srcPath,
-    outputPath,
-    open = OPEN_WORD, // 'DOCS:START',
-    close = CLOSE_WORD, // 'DOCS:END',
-    syntax = SYNTAX, // 'md'
-    transforms = [],
-    beforeMiddleware = [],
-    afterMiddleware = [],
-    debug = false,
-    removeComments = false
-  } = opts
-
-  /*
-  console.log('Open word', open)
-  console.log('Close word', close)
-  console.log('syntax', syntax)
-  // console.log('text', text)
-  /** */
-
-  let foundBlocks = {}
-  try {
-    foundBlocks = parseBlocks(text, {
-      syntax,
-      open,
-      close,
-    })
-  } catch (e) {
-    throw new Error(`${e.message}\nFix content in ${srcPath}\n`)
-  }
-
-  // if (debug) {
-  //   console.log(`foundBlocks ${srcPath}`)
-  //   deepLog(foundBlocks)
-  // }
-  /*
-  deepLog(foundBlocks)
-  process.exit(1)
-  /** */
-  const { COMMENT_OPEN_REGEX, COMMENT_CLOSE_REGEX } = foundBlocks
-
-  const blocksWithTransforms = foundBlocks.blocks
-    .filter((block) => block.type)
-    .map((block, i) => {
-      const transform = block.type
-      delete block.type
-      return Object.assign({ transform }, block)
-    })
-
-  
-  const regexInfo = {
-    blocks: foundBlocks.pattern,
-    open: COMMENT_OPEN_REGEX,
-    close: COMMENT_CLOSE_REGEX,
-  }
-  // console.log('blocksWithTransforms', blocksWithTransforms)
-  // process.exit(1)
-
-  const transformsToRun = sortTranforms(blocksWithTransforms, transforms)
-  // .map((transform) => {
-  //   return {
-  //     ...transform,
-  //     srcPath
-  //   }
-  // })
-  // console.log('transformsToRun', transformsToRun)
-
-  // if (!transformsToRun.length) {
-  //   process.exit(1)
-  // }
-  // console.log('transformsToRun', transformsToRun)
-  let missingTransforms = []
-  let updatedContents = await transformsToRun.reduce(async (contentPromise, originalMatch) => {
-    const md = await contentPromise
-    /* Apply Before middleware to all transforms */
-    const match = await applyMiddleware(originalMatch, md, beforeMiddleware)
-    const { block, content, open, close, transform, options, context } = match
-    // console.log("MATCH", match)
-    const closeTag = close.value
-    const openTag = open.value
-    
-    /* Run transform plugins */
-    let tempContent = content.value
-    // console.log('transform', transform)
-    const currentTransformFn = getTransform(transform, transforms)
-    /* Run each transform */
-    if (currentTransformFn) {
-      // console.log('context', context)
-      let returnedContent
-      /* DISABLED legacy syntax */
-      /* // Support for legacy syntax... maybe later
-      if (context && context.isLegacy) {
-        console.log(`CALL legacy ${transform}`, srcPath)
-        // backward compat maybe
-        // CODE(content, options, config)
-        returnedContent = await currentTransformFn(content.value, options, { 
-          originalPath: srcPath
-        })
-      } else {
-        returnedContent = await currentTransformFn(transformApi({
-          srcPath,
-          ...match,
-          regex: regexInfo,
-          originalContents: text,
-          currentContents: md,
-        }, config))
-      }
-      /** */
-
-      returnedContent = await currentTransformFn(
-        transformApi({
-          srcPath,
-          ...match,
-          regex: regexInfo,
-          originalContents: text,
-          currentContents: md,
-        }, config)
-      )
-
-      /* Run each transform */
-      // console.log('config', config)
-
-      // console.log('returnedContent', returnedContent)
-      // process.exit(1)
-
-     
-      if (returnedContent) {
-        tempContent = returnedContent
-      }
-    }
-
-    /* Apply After middleware to all transforms */
-    const afterContent = await applyMiddleware({
-      ...match,
-      ...{
-        content: {
-          ...match.content,
-          value: tempContent
-        }
-      }
-    }, md, afterMiddleware)
-    /*
-    console.log('afterContent', afterContent)
-    process.exit(1)
-    /** */
-
-    if (debug) {
-      // console.log('afterContent', afterContent)
-    }
-
-    if (!currentTransformFn) {
-      missingTransforms.push(afterContent)
-      // console.log(`Missing "${transform}" transform`)
-    }
-
-    const newContent = afterContent.content.value
-    const formattedNewContent = (options.noTrim) ? newContent : trimString(newContent)
-    // console.log('formattedNewContent', formattedNewContent)
-    /* Remove any conflicting imported comments */
-    const fix = removeConflictingComments(formattedNewContent, COMMENT_OPEN_REGEX, COMMENT_CLOSE_REGEX)
-    /*
-    console.log('fix')
-    deepLog(fix)
-    process.exit(1)
-    /** */
-    if (options.removeComments) {
-      // console.log('removeComments', options.removeComments)
-    }
-    // const fix = stripAllComments(formattedNewContent, foundBlocks.COMMENT_OPEN_REGEX, COMMENT_CLOSE_REGEX)
-
-    // console.log('COMMENT_CLOSE_REGEX', COMMENT_CLOSE_REGEX)
-    // console.log('formattedNewContent', formattedNewContent)
-    // console.log('fix', fix)
-
-    let preserveIndent = 0
-    if (match.content.indentation) {
-      preserveIndent = match.content.indentation
-    } else if (preserveIndent === 0) {
-      preserveIndent = block.indentation.length
-    }
-    // console.log('preserveIndent', preserveIndent)
-    let addTrailingNewline = ''
-    if (context.isMultiline && !fix.endsWith('\n') && fix !== '' && closeTag.indexOf('\n') === -1) {
-      addTrailingNewline = '\n'
-    }
-
-    let addLeadingNewline = ''
-    if (context.isMultiline && !fix.startsWith('\n') && fix !== '' && openTag.indexOf('\n') === -1) {
-      addLeadingNewline = '\n'
-    }
-
-    let fixWrapper = ''
-    /* If block wasn't multiline but the contents ARE multiline fix the block */
-    if (!context.isMultiline && fix.indexOf('\n') > -1) {
-      fixWrapper = '\n'
-    }
-
-    // console.log("OPEN TAG", `"${openTag}"`)
-    // console.log("CLOSE TAG", `"${closeTag}"`)
-    
-    const indent = addLeadingNewline + indentString(fix, preserveIndent) + addTrailingNewline
-    const newCont = `${openTag}${fixWrapper}${indent}${fixWrapper}${closeTag}`
-    /* Replace original contents */
-    // Must use replacer function because strings get coerced to regex or something
-    const newContents = md.replace(block.value, () => newCont)
-    /*
-    deepLog(newContents)
-    process.exit(1)
-    /** */
-    return Promise.resolve(newContents)
-  }, Promise.resolve(text))
-
-  // console.log('updatedContents')
-  // deepLog(updatedContents)
-  // process.exit(1)
-
-  // if (debug) {
-  //   console.log('Output Markdown')
-  //   console.log(updatedContents)
-  // }
-
-  /*
-  if (missingTransforms.length) {
-    console.log('missingTransforms', missingTransforms)
-    let matchOne = missingTransforms[1]
-    matchOne = missingTransforms[missingTransforms.length - 1]
-    // console.log('matchOne', matchOne)
-    const { block, transform, args } = matchOne
-    const { openTag, closeTag, content, contentStart, contentEnd, start, end} = block
-
-    // console.log('contentStart', contentStart)
-    // console.log('contentEnd', contentEnd)
-    // console.log('original text between', `"${getTextBetweenChars(md, contentStart, contentEnd)}"`)
-    // console.log('original block between', `"${getTextBetweenChars(md, start, end)}"`)
-  }
-  /** */
-
-  // console.log('detect slow srcPath', srcPath)
-
-  const isNewPath = srcPath !== outputPath
-
-  if (removeComments && !isNewPath) {
-    throw new Error('"removeComments" can only be used if "outputPath" option is set. Otherwise this will break doc generation.')
-  }
-
-  /* Strip block comments from output files */
-  const stripComments = isNewPath && removeComments
-
-  // console.log('srcPath', srcPath)
-  // console.log('outputPath', outputPath)
-  // console.log('updatedContents', updatedContents)
-  // console.log('text', text)
-  // process.exit(1)
-  const result = {
-    /* Has markdown content changed? */
-    isChanged: text !== updatedContents,
-    isNewPath,
-    stripComments,
-    srcPath,
-    outputPath,
-    // config,
-    transforms: transformsToRun,
-    missingTransforms,
-    originalContents: text,
-    updatedContents,
-  }
-  /*
-  console.log('result')
-  deepLog(result)
-  process.exit(1)
-  /** */
-  return result
-}
-
-function transformApi(stuff, opts) {
-  const { transforms, srcPath, outputPath, ...rest } = opts
-  return {
-    transform: stuff.transform,
-    content: stuff.content.value,
-    options: stuff.options || {},
-    srcPath: stuff.srcPath,
-    outputPath: outputPath,
-    /* Library settings */
-    settings: {
-      ...rest,
-      regex: stuff.regex,
-    },
-    // blockContent: stuff.content.value,
-    currentFileContent: stuff.currentContents,
-    originalFileContent: stuff.originalContents,
-    /* Methods */
-    getCurrentContent: () => stuff.currentContents,
-    getOriginalContent: () => stuff.originalContents,
-    getOriginalBlock: () => stuff,
-    getBlockDetails: (content) => {
-      /* Re-parse current file for updated positions */
-      return getDetails({
-        contents: content || stuff.currentContents,
-        openValue: stuff.open.value,
-        srcPath: stuff.srcPath,
-        index: stuff.index,
-        opts: opts
-      })
-    },
-    // getOriginalBlockDetails: () => {
-    //   return getDetails({
-    //     contents: stuff.originalContents,
-    //     openValue: stuff.open.value,
-    //     srcPath: stuff.srcPath,
-    //     index: stuff.index,
-    //     opts: opts
-    //   })
-    // },
-  }
-}
-
-function getDetails({
-  contents,
-  openValue,
-  srcPath,
-  index,
-  opts
-}) {
-  /* Re-parse current file for updated positions */
-  const blockData = parseBlocks(contents, opts)
-  // console.log('blockData', blockData)
-
-  const matchingBlocks = blockData.blocks.filter((block) => {
-    return block.open.value === openValue
-  })
-
-  if (!matchingBlocks.length) {
-    return {}
-  }
-
-  let foundBlock = matchingBlocks[0]
-  if (matchingBlocks.length > 1 && index) {
-    foundBlock = matchingBlocks.filter((block) => {
-      return block.index === index
-    })[0]
-  }
-
-  if (srcPath) {
-    const location = getCodeLocation(srcPath, foundBlock.block.lines[0])
-    foundBlock.sourceLocation = location
-  }
-  return foundBlock
-}
-
-/**
- * Remove conflicting comments that might have been inserted from transforms
- * @param {*} content 
- * @param {*} openPattern 
- * @param {*} closePattern 
- * @returns
- */
- function removeConflictingComments(content, openPattern, closePattern) {
-  // console.log('openPattern', openPattern)
-  // console.log('closePattern', closePattern)
-  const removeOpen = content.replace(openPattern, '')
-  // TODO this probably needs to be a loop for larger blocks
-  closePattern.lastIndex = 0; // reset regex
-  const hasClose = closePattern.exec(content)
-  // console.log('closePattern', closePattern)
-  // console.log('has', content)
-  // console.log('hasClose', hasClose)
-  if (!hasClose) {
-    return removeOpen
-  }
-  const closeTag = `${hasClose[2]}${hasClose[3] || ''}`
-  // console.log('closeTag', closeTag)
-  return removeOpen
-    .replace(closePattern, '')
-    // .replaceAll(closeTag, '')
-    /* Trailing new line */
-    .replace(/\n$/, '')
-}
-
-function applyMiddleware(data, md, middlewares) {
-  return middlewares.reduce(async (acc, curr) => {
-    const realAcc = await acc
-    // console.log(`Running "${curr.name}" Middleware on "${realAcc.transform}" block`)
-    const updatedContent = await curr.transform(realAcc, md)
-    // realAcc.block.content = updatedContent
-    return Promise.resolve({
-      ...realAcc,
-      ...{
-        content: {
-          ...realAcc.content,
-          value: updatedContent
-        }
-      }
-    })
-  }, Promise.resolve(data))
-}
-
-/**
- * Get Transform function
- * @param {string} name - transform name
- * @param {object} transforms - transform fns
- * @returns {function}
- */
-function getTransform(name, transforms = {}) {
-  return transforms[name] || transforms[name.toLowerCase()]
-}
-
-function sortTranforms(foundTransForms, registeredTransforms) {
-  // console.log('transforms', transforms)
-  if (!foundTransForms) return []
-  return foundTransForms.sort((a, b) => {
-    // put table of contents (TOC) at end of tranforms
-    if (a.transform === 'TOC' || a.transform === 'sectionToc') return 1
-    if (b.transform === 'TOC' || b.transform === 'sectionToc') return -1
-    return 0
-  }).map((item) => {
-    if (getTransform(item.transform, registeredTransforms)) {
-      return item
-    }
-    return {
-      ...item,
-      context: {
-        ...item.context,
-        isMissing: true,
-      }
-    }
-  })
-}
+const { blockTransformer } = require('comment-block-transformer')
 
 module.exports = {
-  processContents
+  processContents: blockTransformer
 }

package/src/transforms/code/index.js

@@ -2,7 +2,7 @@ const fs = require('fs')
 const path = require('path')
 const { remoteRequest } = require('../../utils/remoteRequest')
 const { isLocalPath } = require('../../utils/fs')
-const { deepLog } = require('../../utils/logs')
+const { deepLog } = require('../../../src/utils/logs')
 const { 
   getLineCount,
   getTextBetweenLines,
@@ -27,15 +27,15 @@ const RAW_URL_LIKE = /^([A-Za-z0-9_]+)\.([A-Za-z0-9_]*)\/(.*)/
  * @property {boolean} [trimDeadCode] - Remove multi-line comments that start with `//` from the code.
  * @example
    ```md
-   <!-- doc-gen CODE src="./relative/path/to/code.js" -->
+   <!-- docs CODE src="./relative/path/to/code.js" -->
    This content will be dynamically replaced with code from the file
-   <!-- end-doc-gen -->
+   <!-- /docs -->
    ```
-  
+
    ```md
-   <!-- doc-gen CODE src="./relative/path/to/code.js" lines="22-44" -->
+   <!-- docs CODE src="./relative/path/to/code.js" lines="22-44" -->
    This content will be dynamically replaced with code from the file lines 22 through 44
-   <!-- end-doc-gen -->
+   <!-- /docs -->
    ```
  */
 

package/src/transforms/fileTree.js

@@ -0,0 +1,213 @@
+const fs = require('fs')
+const path = require('path')
+
+/**
+ * Options for configuring the file tree table of contents.
+ * @typedef {Object} FileTreeTransformOptions
+ * @property {string} [src="."] - The directory path to generate the file tree for. Default is `.` (current directory).
+ * @property {number} [maxDepth=3] - Maximum depth to traverse in the directory tree. Default is `3`.
+ * @property {boolean} [includeFiles=true] - Whether to include files in the tree or just directories. Default is `true`.
+ * @property {string[]} [exclude=[]] - Array of glob patterns to exclude from the tree.
+ * @property {boolean} [showSize=false] - Whether to show file sizes. Default is `false`.
+ * @property {string} [format="tree"] - Output format: "tree" or "list". Default is `"tree"`.
+ * @example
+   ```md
+   <!-- docs fileTree src="./src" maxDepth=2 -->
+   file tree will be generated here
+   <!-- /docs -->
+   ```
+ */
+
+/**
+ * Generate a file tree table of contents
+ * @param {Object} api - The markdown-magic API object
+ * @returns {string} The generated file tree markdown
+ */
+module.exports = function fileTree(api) {
+  const { options, srcPath } = api
+  /** @type {FileTreeTransformOptions} */
+  const opts = options || {}
+  
+  const targetPath = opts.src || '.'
+  const maxDepth = opts.maxDepth ? Number(opts.maxDepth) : 3
+  const includeFiles = opts.includeFiles !== false
+  const exclude = opts.exclude || []
+  const showSize = opts.showSize === true
+  const format = opts.format || 'tree'
+  
+  // Resolve the target path relative to the source file
+  const fileDir = path.dirname(srcPath)
+  const resolvedPath = path.resolve(fileDir, targetPath)
+  
+  try {
+    const tree = generateFileTree(resolvedPath, {
+      maxDepth,
+      includeFiles,
+      exclude,
+      showSize,
+      currentDepth: 0
+    })
+    
+    if (format === 'list') {
+      return formatAsList(tree)
+    }
+    
+    return formatAsTree(tree)
+  } catch (error) {
+    console.error(`Error generating file tree for ${resolvedPath}:`, error.message)
+    return `<!-- Error: Could not generate file tree for ${targetPath} -->`
+  }
+}
+
+/**
+ * Generate file tree structure
+ * @param {string} dirPath - Directory path to scan
+ * @param {Object} options - Options for tree generation
+ * @returns {Object} Tree structure
+ */
+function generateFileTree(dirPath, options) {
+  const { maxDepth, includeFiles, exclude, showSize, currentDepth } = options
+  
+  if (currentDepth >= maxDepth) {
+    return { type: 'directory', name: path.basename(dirPath), children: [], truncated: true }
+  }
+  
+  let items
+  try {
+    items = fs.readdirSync(dirPath)
+  } catch (error) {
+    return { type: 'directory', name: path.basename(dirPath), children: [], error: true }
+  }
+  
+  // Filter out excluded items
+  items = items.filter(item => {
+    // Skip hidden files and common ignored directories
+    if (item.startsWith('.') && !item.match(/\.(md|txt|json)$/)) {
+      return false
+    }
+    if (['node_modules', '.git', '.DS_Store', 'dist', 'build'].includes(item)) {
+      return false
+    }
+    
+    // Apply custom exclude patterns
+    return !exclude.some(pattern => {
+      const regex = new RegExp(pattern.replace(/\*/g, '.*'))
+      return regex.test(item)
+    })
+  })
+  
+  const children = []
+  
+  for (const item of items) {
+    const itemPath = path.join(dirPath, item)
+    const stats = fs.statSync(itemPath)
+    
+    if (stats.isDirectory()) {
+      const subTree = generateFileTree(itemPath, {
+        ...options,
+        currentDepth: currentDepth + 1
+      })
+      children.push(subTree)
+    } else if (includeFiles) {
+      children.push({
+        type: 'file',
+        name: item,
+        size: showSize ? stats.size : undefined
+      })
+    }
+  }
+  
+  // Sort: directories first, then files, alphabetically
+  children.sort((a, b) => {
+    if (a.type !== b.type) {
+      return a.type === 'directory' ? -1 : 1
+    }
+    return a.name.localeCompare(b.name)
+  })
+  
+  return {
+    type: 'directory',
+    name: path.basename(dirPath) || path.basename(path.resolve(dirPath)),
+    children
+  }
+}
+
+/**
+ * Format tree as ASCII tree structure
+ * @param {Object} tree - Tree structure
+ * @returns {string} Formatted tree
+ */
+function formatAsTree(tree) {
+  const lines = []
+  
+  function traverse(node, prefix = '', isLast = true) {
+    const connector = isLast ? '└── ' : '├── '
+    const name = node.type === 'directory' ? `${node.name}/` : node.name
+    const size = node.size ? ` (${formatBytes(node.size)})` : ''
+    
+    lines.push(`${prefix}${connector}${name}${size}`)
+    
+    if (node.children && node.children.length > 0) {
+      const extension = isLast ? '    ' : '│   '
+      node.children.forEach((child, index) => {
+        const childIsLast = index === node.children.length - 1
+        traverse(child, prefix + extension, childIsLast)
+      })
+    }
+    
+    if (node.truncated) {
+      const extension = isLast ? '    ' : '│   '
+      lines.push(`${prefix}${extension}...`)
+    }
+  }
+  
+  traverse(tree)
+  
+  return '```\n' + lines.join('\n') + '\n```'
+}
+
+/**
+ * Format tree as a list
+ * @param {Object} tree - Tree structure
+ * @returns {string} Formatted list
+ */
+function formatAsList(tree) {
+  const lines = []
+  
+  function traverse(node, depth = 0) {
+    const indent = '  '.repeat(depth)
+    const name = node.type === 'directory' ? `**${node.name}/**` : node.name
+    const size = node.size ? ` *(${formatBytes(node.size)})*` : ''
+    
+    lines.push(`${indent}- ${name}${size}`)
+    
+    if (node.children && node.children.length > 0) {
+      node.children.forEach(child => {
+        traverse(child, depth + 1)
+      })
+    }
+    
+    if (node.truncated) {
+      lines.push(`${indent}  - ...`)
+    }
+  }
+  
+  traverse(tree)
+  
+  return lines.join('\n')
+}
+
+/**
+ * Format bytes as human readable string
+ * @param {number} bytes - Bytes to format
+ * @returns {string} Formatted string
+ */
+function formatBytes(bytes) {
+  if (bytes === 0) return '0 B'
+  
+  const k = 1024
+  const sizes = ['B', 'KB', 'MB', 'GB']
+  const i = Math.floor(Math.log(bytes) / Math.log(k))
+  
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(1)) + ' ' + sizes[i]
+}