markdown-magic 3.6.5 → 4.0.0

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`
@@ -20,12 +21,12 @@ const transforms = {
    *
    * **Example:**
    * ```md
-   * <!-- doc-gen TOC -->
+   * <!-- docs TOC -->
    * toc will be generated here
-   * <!-- end-doc-gen -->
+   * <!-- /docs -->
    * ```
    *
-   * Default `matchWord` is `doc-gen`
+   * Default `matchWord` is `docs`
    *
    * ---
    * @param {string} content The current content of the comment block
@@ -47,18 +48,18 @@ const transforms = {
    *
    * **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 -->
    *  ```
-   * 
-   * Default `matchWord` is `doc-gen`
+   *
+   * Default `matchWord` is `docs`
    *
    * ---
    * @param {string} content The current content of the comment block
@@ -76,12 +77,12 @@ const transforms = {
    *
    * **Example:**
    * ```md
-   * <!-- doc-gen FILE src=./path/to/file -->
+   * <!-- docs FILE src=./path/to/file -->
    * This content will be dynamically replaced from the local file
-   * <!-- end-doc-gen -->
+   * <!-- /docs -->
    * ```
    *
-   * Default `matchWord` is `doc-gen`
+   * Default `matchWord` is `docs`
    *
    * ---
    * @param {string} content The current content of the comment block
@@ -99,12 +100,12 @@ const transforms = {
    *
    * **Example:**
    * ```md
-   * <!-- doc-gen REMOTE url=http://url-to-raw-md-file.md -->
+   * <!-- docs REMOTE url=http://url-to-raw-md-file.md -->
    * This content will be dynamically replaced from the remote url
-   * <!-- end-doc-gen -->
+   * <!-- /docs -->
    * ```
    *
-   * Default `matchWord` is `doc-gen`
+   * Default `matchWord` is `docs`
    *
    * ---
    * @param {string} content The current content of the comment block
@@ -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
+   * <!-- docs fileTree src="./src" maxDepth=2 -->
+   * file tree will be generated here
+   * <!-- /docs -->
+   * ```
+   *
+   * **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 `docs`
+   *
+   * ---
+   * @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
    *
@@ -125,12 +193,12 @@ const transforms = {
    *
    * **Example:**
    * ```md
-   * <!-- doc-gen install -->
+   * <!-- docs install -->
    * Installation instructions will be generated here
-   * <!-- end-doc-gen -->
+   * <!-- /docs -->
    * ```
    *
-   * Default `matchWord` is `doc-gen`
+   * Default `matchWord` is `docs`
    *
    * ---
    * @param {string} content The current content of the comment block

package/src/transforms/install.js

@@ -11,12 +11,12 @@ const path = require('path')
  *
  * **Example:**
  * ```md
- * <!-- doc-gen INSTALL packageName=my-package -->
+ * <!-- docs INSTALL packageName=my-package -->
  * Installation instructions will be generated here
- * <!-- end-doc-gen -->
+ * <!-- /docs -->
  * ```
  *
- * Default `matchWord` is `doc-gen`
+ * Default `matchWord` is `docs`
  *
  * ---
  * @param {string} content The current content of the comment block

package/src/transforms/sectionToc.js

@@ -5,15 +5,15 @@ const { readFile } = require('../utils/fs')
 const details = require('../utils/details')
 
 module.exports = async function sectionToc(api) {
-  const { options, currentFileContent, originalFileContent, srcPath, getBlockDetails } = api
+  const { options, currentContent, originalContent, srcPath, getBlockDetails } = api
   const opts = options || {}
   let { collapseText, collapse } = opts
   /* Sub table of contents */
-  const originalBlock = getBlockDetails(originalFileContent)
-  const closestHeading = findClosestParentHeading(originalFileContent, originalBlock.block.start)
+  const originalBlock = getBlockDetails(originalContent)
+  const closestHeading = findClosestParentHeading(originalContent, originalBlock.block.start)
   // console.log('closestHeading', closestHeading)
   
-  const subToc = await generateToc(currentFileContent, {
+  const subToc = await generateToc(currentContent, {
     ...opts,
     normalizeLevels: true,
     // Set sub table of contents

package/src/transforms/toc.js

@@ -11,15 +11,15 @@ const sectionToc = require('./sectionToc')
  * @property {number} [maxDepth=4] - Maximum depth of headings to include in the table of contents. Default is `4`.
  * @example
    ```md
-   <!-- doc-gen (TOC) -->
+   <!-- docs (TOC) -->
    toc will be generated here
-   <!-- end-doc-gen -->
-   ``` 
+   <!-- /docs -->
+   ```
  */
 
 module.exports = async function TOC(api) {
   // console.log("TOC API", api)
-  const { currentFileContent, srcPath, getBlockDetails } = api
+  const { currentContent, srcPath, getBlockDetails } = api
   /** @type {ToCTransformOptions} */
   const options = api.options || {}
   // console.log("TOC OPTIONS", options)
@@ -33,8 +33,8 @@ module.exports = async function TOC(api) {
     return sectionToc(api)
   }
 
-  opts.firsth1 = (opts.firsth1) ? true : false
-  let contents = currentFileContent
+  opts.firsth1 = (opts.firsth1 || opts.firstH1) ? true : false
+  let contents = currentContent
   // console.log('contents', contents)
 
   let collapseText = opts.collapseText
@@ -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/transforms/wordCount.js

@@ -1,5 +1,6 @@
 const { getWordCount } = require('../utils/text')
 
-module.exports = function wordCount({ currentFileContent }) {
-  return getWordCount(currentFileContent)
+module.exports = function wordCount(api) {
+  const { currentContent } = api
+  return getWordCount(currentContent)
 }

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.js

@@ -9,10 +9,21 @@ const { readdir, stat, readFile } = fs
 
 const IS_HIDDEN_FILE = /(^|[\\\/])\.[^\\\/\.]/g
 
+/**
+ * Check if value is a RegExp
+ * @param {any} thing - Value to check
+ * @returns {boolean} True if value is RegExp
+ */
 function isRegex(thing) {
   return (thing instanceof RegExp)
 }
 
+/**
+ * Write file with directory creation if needed
+ * @param {string} filePath - File path to write to
+ * @param {string} content - Content to write
+ * @returns {Promise<void>}
+ */
 async function writeFile(filePath, content) {
   try {
     await fs.writeFile(filePath, content)
@@ -69,6 +80,12 @@ async function escalade(start, callback) {
 
 // }
 
+/**
+ * Convert absolute path to relative path
+ * @param {string} file - Absolute file path
+ * @param {string} cwd - Current working directory
+ * @returns {string} Relative path
+ */
 function convertToRelativePath(file, cwd) {
   return file.replace(cwd, '').replace(/^\//, '')
 }
@@ -165,6 +182,11 @@ function depth(string) {
   return path.normalize(string).split(path.sep).length - 1;
 }
 
+/**
+ * Check if path is local (not remote)
+ * @param {string} filePath - File path to check
+ * @returns {boolean} True if path is local
+ */
 function isLocalPath(filePath) {
   if (filePath.startsWith('github.com/') || filePath.startsWith('raw.githubusercontent.com/')) return false
   return _isLocalPath(filePath)

package/src/utils/fs.test.js

@@ -26,8 +26,8 @@ test('Finds file from dir', async () => {
 })
 
 test('getGitignoreContents', async () => {
-  const files = await getGitignoreContents()
-  /*
+  const files = await getGitignoreContents(path.resolve(__dirname, '../../', '.gitignore'))
+  //*
   console.log('files', files)
   /** */
   assert.is(Array.isArray(files), true)
@@ -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/index.js

@@ -1,12 +1,33 @@
 
+/**
+ * Filter function to get only unique values
+ * @param {any} value - Current value
+ * @param {number} index - Current index
+ * @param {any[]} self - Original array
+ * @returns {boolean} True if value is unique
+ */
 function onlyUnique(value, index, self) {
   return self.indexOf(value) === index
 }
 
+/**
+ * Get code location string in format path:line:column
+ * @param {string} srcPath - Source file path
+ * @param {string|number} line - Line number
+ * @param {string} [column='0'] - Column number
+ * @returns {string} Location string
+ */
 function getCodeLocation(srcPath, line, column = '0') {
   return `${srcPath}:${line}:${column}`
 }
 
+/**
+ * Pluralize word based on count
+ * @param {any[]|number} thing - Array or number to count
+ * @param {string} [single=''] - Singular form
+ * @param {string} [plural=''] - Plural form
+ * @returns {string} Singular or plural form
+ */
 function pluralize(thing, single = '', plural = '') {
   const count = Array.isArray(thing) ? thing.length : Number(thing)
   return count === 1 ? single : plural

package/src/utils/regex-timeout.js

@@ -1,7 +1,7 @@
 // https://stackoverflow.com/questions/38859506/cancel-regex-match-if-timeout
 const util = require('util')
 const vm = require('vm')
-const { getBlockRegex } = require('../block-parser')
+const { getBlockRegex } = require('comment-block-parser')
 const { getSyntaxInfo } = require('./syntax')
 
 const goodString = `

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

@@ -1,13 +1,29 @@
 const { syntaxMap } = require('./syntax')
 
+/**
+ * Split string into lines
+ * @param {string} str - Input string
+ * @returns {string[]} Array of lines
+ */
 function getLines(str = '') {
   return str.split(/\r\n|\r|\n/)
 }
 
+/**
+ * Get line count from string
+ * @param {string} str - Input string
+ * @returns {number} Number of lines
+ */
 function getLineCount(str = '') {
   return getLines(str).length
 }
 
+/**
+ * Get row and column position from character index
+ * @param {string} input - Input string
+ * @param {number} indexToFind - Character index to find
+ * @returns {{row: number, col: number}} Row and column position
+ */
 function getRowAndColumnFromCharPos(input, indexToFind) {
   const preChunk = input.substr(0, indexToFind);
   const row = preChunk.split('\n').length - 1
@@ -16,23 +32,50 @@ function getRowAndColumnFromCharPos(input, indexToFind) {
   return { row, col }
 };
 
+/**
+ * Get word count from string
+ * @param {string} str - Input string
+ * @returns {number} Word count
+ */
 function getWordCount(str = '') {
   return str.trim().split(/\s+/).length
 }
 
+/**
+ * Get first character from string
+ * @param {string} str - Input string
+ * @returns {string} First character
+ */
 function getFirstCharacter(str) {
   return str.charAt(0)
 }
 
+/**
+ * Get last character from string
+ * @param {string} str - Input string
+ * @returns {string} Last character
+ */
 function getLastCharacter(str) {
   return str.substr(-1)
 }
 
+/**
+ * Get leading spaces from text
+ * @param {string} text - Input text
+ * @returns {string} Leading spaces
+ */
 function getLeadingSpaces(text) {
   const matches = text.match(/^\s*/)
   return (matches && matches[0]) ? matches[0] : ''
 }
 
+/**
+ * Get text between character positions
+ * @param {string} text - Input text
+ * @param {number} start - Start position
+ * @param {number} end - End position
+ * @returns {string} Text between positions
+ */
 function getTextBetweenChars(text, start, end) {
   return text.slice(start, end)
 }
@@ -56,6 +99,14 @@ function getTextBetweenWords(s, prefix, suffix) {
   return s
 }
 
+/**
+ * Replace text between character positions
+ * @param {string} str - Input string
+ * @param {number} start - Start position
+ * @param {number} end - End position
+ * @param {string} newStr - Replacement string
+ * @returns {string} Modified string
+ */
 function replaceTextBetweenChars(str = '', start, end, newStr) {
   return str.substring(0, start) + newStr + str.substring(end)
 }
@@ -77,22 +128,39 @@ function getTextBetweenLines(content, startLine, endLine) {
   if (startDefined && !endDefined) {
     return lines.slice(startLine - 1, startLine).join('')
   }
-  if (startLine && endLine && parseInt(startLine, 10) <= parseInt(endLine, 10)) {
+  // @ts-ignore
+  if (startLine && endLine && Number(startLine) <= Number(endLine)) {
     return lines.slice(startLine - 1, endLine).join('\n')
   }
 }
 
+/**
+ * Check if string is uppercase
+ * @param {string} str - Input string
+ * @returns {boolean} True if uppercase
+ */
 function isUpperCase(str) {
   return str === str.toUpperCase()
 }
 
 // https://github.com/jamiebuilds/min-indent/blob/master/index.js
+/**
+ * Find minimum indentation in string
+ * @param {string} string - Input string
+ * @returns {number} Minimum indentation level
+ */
 function findMinIndent(string) {
 	const match = string.match(/^[ \t]*(?=\S)/gm)
 	if (!match) return 0
 	return match.reduce((r, a) => Math.min(r, a.length), Infinity)
 }
 
+/**
+ * Strip indentation from string
+ * @param {string} string - Input string
+ * @param {number} [indentation] - Indentation level to strip
+ * @returns {string} String with indentation stripped
+ */
 function stripIndent(string, indentation) {
   const indent = typeof indentation !== 'undefined' ? indentation : findMinIndent(string);
 	if (indent === 0) {
@@ -105,7 +173,7 @@ function stripIndent(string, indentation) {
 /**
  * Trim leading & trailing spaces/line breaks in code and keeps the indentation of the first non-empty line
  * @param {string|number} str 
- * @returns string
+ * @returns {string}
  */
  function trimString(str = '') {
   let content = (typeof str === 'number') ? str.toString() : str
@@ -113,6 +181,15 @@ function stripIndent(string, indentation) {
   return content.replace(/^(?:[\t ]*(?:\r?\n|\r))+|\s+$/g, '')
 }
 
+/**
+ * Add indentation to string
+ * @param {string} string - Input string
+ * @param {number} [count=1] - Number of indentations to add
+ * @param {object} [options={}] - Options for indentation
+ * @param {string} [options.indent=' '] - Character(s) to use for indentation
+ * @param {boolean} [options.includeEmptyLines=false] - Whether to indent empty lines
+ * @returns {string} Indented string
+ */
 function indentString(string, count = 1, options = {}) {
 	const {
 		indent = ' ',
@@ -130,8 +207,8 @@ function indentString(string, count = 1, options = {}) {
 /**
  * Removes the indentation of multiline strings
  * @link https://github.com/victornpb/tiny-dedent/
- * @param  {string} str A template literal string
- * @return {string} A string without the indentation
+ * @param {string} str - A template literal string
+ * @returns {string} A string without the indentation
  */
 function dedentString(str) {
   str = str.replace(/^[ \t]*\r?\n/, ''); // remove leading blank line
@@ -180,7 +257,7 @@ function stripCommentBlockOld(str, syntax = 'md') {
 /**
  * Strip out comment blocks
  * @param {string} str 
- * @param {typeof import('../types')['syntaxType']} syntax 
+ * @param {import('../types').SyntaxType} syntax 
  * @returns {string} clean comment-less string
  */
 function stripComments(str, syntax = 'md') {
@@ -188,11 +265,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
 }
 
 
@@ -291,33 +375,48 @@ function convertCommentSyntax(str, { from, to }) {
 }
 
 /**
- * capitalize first letter
- * @param {string} str 
- * @returns 
+ * Capitalize first letter
+ * @param {string} str - Input string
+ * @returns {string} String with first letter capitalized
  */
 function capitalizeFirstLetter(str) {
   return capitalize(str.charAt(0)) + str.slice(1)
 }
 
 /**
- * capitalize string
- * @param {string} str 
- * @returns 
+ * Capitalize string
+ * @param {string} str - Input string
+ * @returns {string} Capitalized string
  */
 function capitalize(str = '') {
   return str.toUpperCase()
 }
 
+/**
+ * Convert string to camelCase
+ * @param {string} str - Input string
+ * @returns {string} camelCase string
+ */
 function camelCase(str = '') {
   return str.replace(/[-_ ](\w)/g, (_, c) => c.toUpperCase())
 }
 
+/**
+ * Convert string to kebab-case
+ * @param {string} str - Input string
+ * @returns {string} kebab-case string
+ */
 function kebabCase(str = '') {
   return str.replace(/\B([A-Z])/g, '-$1').toLowerCase()
 }
 
 const smallWords = /^(a|an|and|as|at|but|by|en|for|if|in|nor|of|on|or|per|the|to|vs?\.?|via)$/i;
 
+/**
+ * Convert string to Title Case
+ * @param {string} str - Input string
+ * @returns {string} Title Case string
+ */
 function toTitleCase(str = '') {
 	return str.replace(/[A-Za-z0-9\u00C0-\u00FF]+[^\s-]*/g, (match, index, title) => {
 		if (index > 0