markdown-magic 3.6.5 → 3.7.0

package/README.md

@@ -43,6 +43,8 @@ This `README.md` is generated with `markdown-magic` [view the raw file](https://
   - [> CODE](#-code)
   - [> FILE](#-file)
   - [> REMOTE](#-remote)
+  - [> fileTree](#-filetree)
+  - [> install](#-install)
 - [Inline transforms](#inline-transforms)
 - [Legacy v1 & v2 plugins](#legacy-v1--v2-plugins)
 - [Adding Custom Transforms](#adding-custom-transforms)
@@ -267,7 +269,7 @@ Markdown Magic comes with a couple of built-in transforms for you to use or you
 Generate table of contents from markdown file
 
 **Options:**
-- `firsth1` - *boolean* - (optional): Show first h1 of doc in table of contents. Default `false`
+- `firstH1` - *boolean* - (optional): Show first h1 of doc in table of contents. Default `false`
 - `collapse` - *boolean* - (optional): Collapse the table of contents in a detail accordion. Default `false`
 - `collapseText` - *string* - (optional): Text the toc accordion summary
 - `excludeText` - *string* - (optional): Text to exclude in the table of contents. Default `Table of Contents`
@@ -362,6 +364,99 @@ Default `matchWord` is `doc-gen`
 
 ---
 
+| Name | Type | Description |
+|:---------------------------|:---------------:|:-----------|
+| `content` | `string` | The current content of the comment block. |
+| `options` | `object` | The options passed in from the comment declaration. |
+
+### > fileTree
+
+Generate a file tree table of contents
+
+**Options:**
+- `src` (optional): The directory path to generate the file tree for. Default `.` (current directory)
+- `maxDepth` (optional): Maximum depth to traverse in the directory tree. Default `3`
+- `includeFiles` (optional): Whether to include files in the tree or just directories. Default `true`
+- `exclude` (optional): Array of glob patterns to exclude from the tree. Default `[]`
+- `showSize` (optional): Whether to show file sizes. Default `false`
+- `format` (optional): Output format: "tree" or "list". Default `"tree"`
+
+**Example:**
+```md
+<!-- doc-gen fileTree src="./src" maxDepth=2 -->
+file tree will be generated here
+<!-- end-doc-gen -->
+```
+
+**Example Output (tree format):**
+```
+└── src/
+    ├── transforms/
+    │   ├── code/
+    │   │   ...
+    │   ├── fileTree.js
+    │   ├── index.js
+    │   └── toc.js
+    ├── utils/
+    │   ├── fs.js
+    │   ├── logs.js
+    │   └── text.js
+    └── index.js
+```
+
+**Example Output (list format):**
+```md
+- **src/**
+  - **transforms/**
+    - **code/**
+      - ...
+    - fileTree.js
+    - index.js
+    - toc.js
+  - **utils/**
+    - fs.js
+    - logs.js
+    - text.js
+  - index.js
+```
+
+**Example with file sizes:**
+```
+└── src/
+    ├── index.js (15.2 KB)
+    └── package.json (552 B)
+```
+
+Default `matchWord` is `doc-gen`
+
+---
+
+| Name | Type | Description |
+|:---------------------------|:---------------:|:-----------|
+| `content` | `string` | The current content of the comment block. |
+| `options` | `object` | The options passed in from the comment declaration. |
+
+### > install
+
+Generate installation instructions in a markdown table format
+
+**Options:**
+- `packageName` (optional): The name of the package to install. If not provided, will try to read from package.json
+- `isDev` (optional): Whether to install the package as a dev dependency. Default `false`
+- `header` (optional): The header to use for the installation instructions. Default `# Installation`
+- `body` (optional): The body to use for the installation instructions. Default `Install the \`${packageName}\` cli using your favorite package manager.`
+
+**Example:**
+```md
+<!-- doc-gen install -->
+Installation instructions will be generated here
+<!-- end-doc-gen -->
+```
+
+Default `matchWord` is `doc-gen`
+
+---
+
 | Name | Type | Description |
 |:---------------------------|:---------------:|:-----------|
 | `content` | `string` | The current content of the comment block. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "markdown-magic",
-  "version": "3.6.5",
+  "version": "3.7.0",
   "description": "Automatically update markdown files with content from external sources",
   "main": "src/index.js",
   "bin": {

package/src/index.js

@@ -1,10 +1,11 @@
 const path = require('path')
 // @TODO remove this once we have swapped out node-fetch@2.7
-const moduleAlias = require('module-alias') // "Fix" for puncode dep warning in node 22+
-moduleAlias.addAlias('punycode', 'punycode/') // "Fix" for puncode dep warning in node 22+
+const moduleAlias = require('module-alias') // "Fix" for punycode dep warning in node 22+
+moduleAlias.addAlias('punycode', 'punycode/') // "Fix" for punycode dep warning in node 22+
 const { glob, globWithGit } = require('smart-glob')
 const codeTransform = require('./transforms/code')
 const fileTransform = require('./transforms/file')
+const fileTreeTransform = require('./transforms/fileTree')
 const tocTransform = require('./transforms/toc')
 const sectionTocTransform = require('./transforms/sectionToc')
 const wordCountTransform = require('./transforms/wordCount')
@@ -32,6 +33,7 @@ const LINE = '──────────────────────
 const defaultTransforms = {
   CODE: codeTransform,
   FILE: fileTransform,
+  fileTree: fileTreeTransform,
   TOC: tocTransform,
   sectionToc: sectionTocTransform,
   wordCount: wordCountTransform,

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
+   <!-- doc-gen fileTree src="./src" maxDepth=2 -->
+   file tree will be generated here
+   <!-- end-doc-gen -->
+   ``` 
+ */
+
+/**
+ * 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]
+}

package/src/transforms/index.js

@@ -1,5 +1,6 @@
 const code = require('./code')
 const file = require('./file')
+const fileTree = require('./fileTree')
 const remoteContent = require('./remote')
 const toc = require('./toc')
 const sectionToc = require('./sectionToc')
@@ -12,7 +13,7 @@ const transforms = {
    * Generate table of contents from markdown file
    *
    * **Options:**
-   * - `firsth1` - *boolean* - (optional): Show first h1 of doc in table of contents. Default `false`
+   * - `firstH1` - *boolean* - (optional): Show first h1 of doc in table of contents. Default `false`
    * - `collapse` - *boolean* - (optional): Collapse the table of contents in a detail accordion. Default `false`
    * - `collapseText` - *string* - (optional): Text the toc accordion summary
    * - `excludeText` - *string* - (optional): Text to exclude in the table of contents. Default `Table of Contents`
@@ -112,6 +113,73 @@ const transforms = {
    * @return {string} Updated content to place in the content block
    */
   REMOTE: remoteContent,
+  /**
+   * ### > fileTree
+   *
+   * Generate a file tree table of contents
+   *
+   * **Options:**
+   * - `src` (optional): The directory path to generate the file tree for. Default `.` (current directory)
+   * - `maxDepth` (optional): Maximum depth to traverse in the directory tree. Default `3`
+   * - `includeFiles` (optional): Whether to include files in the tree or just directories. Default `true`
+   * - `exclude` (optional): Array of glob patterns to exclude from the tree. Default `[]`
+   * - `showSize` (optional): Whether to show file sizes. Default `false`
+   * - `format` (optional): Output format: "tree" or "list". Default `"tree"`
+   *
+   * **Example:**
+   * ```md
+   * <!-- doc-gen fileTree src="./src" maxDepth=2 -->
+   * file tree will be generated here
+   * <!-- end-doc-gen -->
+   * ```
+   *
+   * **Example Output (tree format):**
+   * ```
+   * └── src/
+   *     ├── transforms/
+   *     │   ├── code/
+   *     │   │   ...
+   *     │   ├── fileTree.js
+   *     │   ├── index.js
+   *     │   └── toc.js
+   *     ├── utils/
+   *     │   ├── fs.js
+   *     │   ├── logs.js
+   *     │   └── text.js
+   *     └── index.js
+   * ```
+   *
+   * **Example Output (list format):**
+   * ```md
+   * - **src/**
+   *   - **transforms/**
+   *     - **code/**
+   *       - ...
+   *     - fileTree.js
+   *     - index.js
+   *     - toc.js
+   *   - **utils/**
+   *     - fs.js
+   *     - logs.js
+   *     - text.js
+   *   - index.js
+   * ```
+   *
+   * **Example with file sizes:**
+   * ```
+   * └── src/
+   *     ├── index.js (15.2 KB)
+   *     └── package.json (552 B)
+   * ```
+   *
+   * Default `matchWord` is `doc-gen`
+   *
+   * ---
+   * @param {string} content The current content of the comment block
+   * @param {object} options The options passed in from the comment declaration
+   * @return {string} Updated content to place in the content block
+   */
+  fileTree: fileTree,
   /**
    * ### > install
    *

package/src/transforms/toc.js

@@ -33,7 +33,7 @@ module.exports = async function TOC(api) {
     return sectionToc(api)
   }
 
-  opts.firsth1 = (opts.firsth1) ? true : false
+  opts.firsth1 = (opts.firsth1 || opts.firstH1) ? true : false
   let contents = currentFileContent
   // console.log('contents', contents)
 
@@ -54,7 +54,7 @@ module.exports = async function TOC(api) {
     trimLeadingHeading: true,
     // maxHeaderLevel: 2, // default: 4
     // title: '**Table of Contents**',
-    // isNotitle: true,
+    // isNoTitle: true,
     // isFolding: true,
     // entryPrefix: '*',
     // processAll: true,

package/src/types.js

@@ -1,6 +1,6 @@
 /**
  * Allowed file syntaxes
- * @typedef {'md' | 'js' | 'yml' | 'yaml'} SyntaxType
+ * @typedef {'md' | 'js' | 'yml' | 'yaml' | 'toml' | 'sql'} SyntaxType
  */
 
 /** @type {SyntaxType} */

package/src/utils/fs.test.js

@@ -42,6 +42,9 @@ test('getGitignoreContents', async () => {
     'misc',
     'misc/**/**.js',
     "__misc",
+    'large-table.md',
+    'large-table.js',
+    'large-table-data.json',
     '**/old-test/cool.md',
     'pids',
     '*.pid',

package/src/utils/syntax.js

@@ -53,6 +53,30 @@ const yaml = {
   }
 }
 
+const sql = {
+  tags: ['/*', '*/'],
+  pattern: [
+    '\/\\*+',
+    '\\*+/'
+  ],
+  singleLineTag: '--',
+  singleLinePattern: '--',
+  singleLine: '--.*$',
+  content: '[\\s\\S]*?'
+}
+
+const toml = {
+  tags: ['#', '#'],
+  pattern: [
+    '#+',
+    '#+'
+  ],
+  singleLineTag: '#',
+  singleLinePattern: '#+',
+  singleLine: '#.*$',
+  content: '[ \\t\\S]*?'
+}
+
 const syntaxMap = {
   // <!-- x -->
   md: html,
@@ -66,8 +90,12 @@ const syntaxMap = {
   jsx: jsx,
   mdx: jsx,
   // ## x ##
+  yml: yaml,
   yaml: yaml,
-  yml: yaml
+  // -- x
+  sql: sql,
+  // # x
+  toml: toml
 }
 
 // Additional comment syntaxes for future

package/src/utils/text.js

@@ -188,11 +188,18 @@ function stripComments(str, syntax = 'md') {
   const [ openPattern, closePattern ] = syntaxData.pattern
   const OR = (syntaxData.singleLine) ? `|\\s?[ \\t]*${syntaxData.singleLine}` : ''
   const CONTENT = syntaxData.content || '[\\s\\S]*?'
-  const pattern = new RegExp(`\\s?[ \\t]*${openPattern}(${CONTENT})?${closePattern}${OR}`, 'gim')
-  // console.log('pattern', pattern)
-  return str.replace(pattern, '')
-  // https://regex101.com/r/XKHU18/5
-  return str.replace(/\s?[ \t]*\/\*[\s\S]*?\*\/|\s?[ \t]*\/\/.*$|\/\*{1,}[\n\*]*(\s?[\s\S]*?)?\*+\//gm, '')
+  
+  // Handle multi-line comments
+  const multiLinePattern = new RegExp(`\\s?[ \\t]*${openPattern}${CONTENT}${closePattern}`, 'gim')
+  let result = str.replace(multiLinePattern, '')
+  
+  // Handle single-line comments if they exist
+  if (syntaxData.singleLine) {
+    const singleLinePattern = new RegExp(`\\s?[ \\t]*${syntaxData.singleLine}.*$`, 'gm')
+    result = result.replace(singleLinePattern, '')
+  }
+  
+  return result
 }
 
 

package/src/utils/text.test.js

@@ -50,7 +50,7 @@ nice
  nice={{ value: nice, cool: "true" }}
  soclose=[jdjdjd, hdhfhfhffh]
  rad="boss"
- cool=true notCool=false
+ cool=true notCool=false
  nooooo={[one, two, 3, 4]}
  numberZero=0,
  xyz=999,
@@ -72,7 +72,7 @@ actual content
 <!-- XYZ:START(cool) xxx
 hhddh=cool -->
 wowow
-whatever we want 
+whatever we want 
 <!-- XYZ:END -->
 
 
@@ -135,7 +135,7 @@ test('Remove Markdown comments', () => {
     '',
     '',
     'wowow',
-    'whatever we want ',
+    'whatever we want ',
     '',
     '',
     'xyz',
@@ -297,6 +297,79 @@ test('Convert comment syntax', () => {
   // assert.equal(typeof parsedValue, 'string')
 })
 
+test('Remove TOML comments', () => {
+  const parsedValue = stripComments(`
+# This is a TOML comment
+title = "TOML Example"
+# Another comment
+[owner]
+name = "Tom Preston-Werner"
+# Inline comment
+organization = "GitHub" # This is an inline comment
+# Multi-line comment
+# that continues
+# on multiple lines
+created = 1979-05-27T07:32:00Z
+
+[database]
+server = "192.168.1.1"
+ports = [ 8001, 8001, 8002 ]
+connection_max = 5000
+enabled = true
+`, 'toml')
+
+  assert.equal(typeof parsedValue, 'string')
+  assert.equal(parsedValue.match(/#/), null)
+  assert.equal(parsedValue.split('\n'), [
+    '',
+    'title = "TOML Example"',
+    '[owner]',
+    'name = "Tom Preston-Werner"',
+    'organization = "GitHub"',
+    'created = 1979-05-27T07:32:00Z',
+    '',
+    '[database]',
+    'server = "192.168.1.1"',
+    'ports = [ 8001, 8001, 8002 ]',
+    'connection_max = 5000',
+    'enabled = true',
+    ''
+  ])
+})
+
+test('Remove SQL comments', () => {
+  const parsedValue = stripComments(`
+-- This is a single line comment
+SELECT * FROM users
+-- Another single line comment
+WHERE id = 1
+/* This is a multi-line
+   comment that spans
+   multiple lines */
+
+AND active = true
+SELECT name -- inline comment
+FROM products
+WHERE price > 100 /* another inline comment */
+`, 'sql')
+
+  console.log('parsedValue', parsedValue)
+  assert.equal(typeof parsedValue, 'string')
+  assert.equal(parsedValue.match(/--/), null, 'SQL comments should be removed 1')
+  assert.equal(parsedValue.match(/\/\*/), null, 'SQL comments should be removed 2')
+  assert.equal(parsedValue.match(/\*\//), null, 'SQL comments should be removed 3')
+  assert.equal(parsedValue.split('\n'), [
+    '',
+    'SELECT * FROM users',
+    'WHERE id = 1',
+    '',
+    'AND active = true',
+    'SELECT name',
+    'FROM products',
+    'WHERE price > 100',
+    ''
+  ])
+})
 
 function logOutput(value) {
   console.log(value.split('\n'))