markdown-magic 3.0.3 → 3.0.5

package/lib/process-contents.js

@@ -2,30 +2,48 @@ 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 } = require('./defaults')
+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 {object} config 
+ * @param {ProcessContentConfig} config 
  * @returns 
  */
- async function processContents(text, config = {}) {
+async function processContents(text, config) {
+  const opts = config || {}
+
   const {
     srcPath,
     outputPath,
     open = OPEN_WORD, // 'DOCS:START',
     close = CLOSE_WORD, // 'DOCS:END',
-    syntax = 'md',
-    transforms,
+    syntax = SYNTAX, // 'md'
+    transforms = [],
     beforeMiddleware = [],
     afterMiddleware = [],
     debug = false,
-  } = config
+    removeComments = false
+  } = opts
 
   /*
-  console.log('OPEN_WORD', open)
-  console.log('CLOSE_WORD', close)
+  console.log('Open word', open)
+  console.log('Close word', close)
   console.log('syntax', syntax)
   // console.log('text', text)
   /** */
@@ -38,7 +56,7 @@ const { OPEN_WORD, CLOSE_WORD } = require('./defaults')
       close,
     })
   } catch (e) {
-    throw new Error(`${e.message} in file ${srcPath}\n`)
+    throw new Error(`${e.message}\nFix content in ${srcPath}\n`)
   }
 
   if (debug) {
@@ -82,7 +100,7 @@ const { OPEN_WORD, CLOSE_WORD } = require('./defaults')
   // }
   // console.log('transformsToRun', transformsToRun)
   let missingTransforms = []
-  const updatedContents = await transformsToRun.reduce(async (contentPromise, originalMatch) => {
+  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)
@@ -148,6 +166,7 @@ const { OPEN_WORD, CLOSE_WORD } = require('./defaults')
         }
       }
     }, md, afterMiddleware)
+
     if (debug) {
       console.log('afterContent', afterContent)
     }
@@ -161,8 +180,12 @@ const { OPEN_WORD, CLOSE_WORD } = require('./defaults')
     const formattedNewContent = (options.noTrim) ? newContent : trimString(newContent)
     // console.log('formattedNewContent', formattedNewContent)
     /* Remove any conflicting imported comments */
-    const fix = removeConflictingComments(formattedNewContent, foundBlocks.commentOpen, COMMENT_CLOSE_REGEX)
-    // const fix = stripAllComments(formattedNewContent, foundBlocks.commentOpen, COMMENT_CLOSE_REGEX)
+    const fix = removeConflictingComments(formattedNewContent, COMMENT_OPEN_REGEX, COMMENT_CLOSE_REGEX)
+    // console.log('fix', fix)
+    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)
@@ -175,10 +198,10 @@ const { OPEN_WORD, CLOSE_WORD } = require('./defaults')
     return Promise.resolve(newContents)
   }, Promise.resolve(text))
 
-  if (debug) {
-    console.log('Output Markdown')
-    console.log(updatedContents)
-  }
+  // if (debug) {
+  //   console.log('Output Markdown')
+  //   console.log(updatedContents)
+  // }
 
   /*
   if (missingTransforms.length) {
@@ -198,22 +221,32 @@ const { OPEN_WORD, CLOSE_WORD } = require('./defaults')
 
   // 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)
   const result = {
     /* Has markdown content changed? */
     isChanged: text !== updatedContents,
-    isNewPath: srcPath !== outputPath,
+    isNewPath,
+    stripComments,
     srcPath,
     outputPath,
     // config,
     transforms: transformsToRun,
     missingTransforms,
     originalContents: text,
-    updatedContents
+    updatedContents,
   }
-
   // console.log('result')
   // deepLog(result)
-
   return result
 }
 
@@ -225,15 +258,16 @@ function transformApi(stuff, opts) {
     options: stuff.options || {},
     srcPath: stuff.srcPath,
     outputPath: outputPath,
+    /* Library settings */
     settings: {
       ...rest,
       regex: stuff.regex,
     },
-
     // blockContent: stuff.content.value,
-    fileContent: stuff.currentContents,
+    currentFileContent: stuff.currentContents,
     originalFileContent: stuff.originalContents,
     /* Methods */
+    getCurrentContent: () => stuff.currentContents,
     getOriginalContent: () => stuff.originalContents,
     getOriginalBlock: () => stuff,
     getBlockDetails: (content) => {
@@ -267,6 +301,7 @@ function getDetails({
 }) {
   /* 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
@@ -298,6 +333,8 @@ function getDetails({
  * @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
@@ -311,7 +348,8 @@ function getDetails({
   const closeTag = `${hasClose[2]}${hasClose[3] || ''}`
   // console.log('closeTag', closeTag)
   return removeOpen
-    .replaceAll(closeTag, '')
+    .replace(closePattern, '')
+    // .replaceAll(closeTag, '')
     /* Trailing new line */
     .replace(/\n$/, '')
 }

package/lib/process-file.js

@@ -1,11 +1,21 @@
 const path = require('path')
 const isValidFile = require('is-valid-path')
-const { readFile } = require('./utils/fs')
+const { readFile, writeFile } = require('./utils/fs')
 const { processContents } = require('./process-contents')
-// const { OPEN_WORD, CLOSE_WORD } = require('./defaults')
 
 async function processFile(opts = {}) {
-  const { content, syntax } = opts
+  const { content, syntax, outputPath, dryRun, patterns, output = {} } = opts
+  const outputDir = output.directory || opts.outputDir
+
+  let applyTransformsToSource = false
+  if (typeof output.applyTransformsToSource !== 'undefined') {
+    applyTransformsToSource = output.applyTransformsToSource
+    // @ts-ignore
+  } else if (typeof opts.applyTransformsToSource !== 'undefined') {
+    // @ts-ignore
+    applyTransformsToSource = opts.applyTransformsToSource
+  }
+
   let srcPath = opts.srcPath
   if (srcPath && content) {
     throw new Error(`Can't set both "srcPath" & "content"`) 
@@ -25,11 +35,37 @@ async function processFile(opts = {}) {
   if (srcPath && !syntaxType) {
     syntaxType = path.extname(srcPath).replace(/^\./, '')
   }
-  return processContents(fileContents, {
+  // console.log('processFile order', srcPath)
+
+  const result = await processContents(fileContents, {
     ...opts,
+    outputPath,
     srcPath,
     syntax: syntaxType,
   })
+  // console.log('result', result)
+
+  if (dryRun) {
+    return result
+  }
+
+  /* If it's changed or its a new file to write */
+  if (result.isChanged || result.isNewPath) {
+    let cleanContents = result.updatedContents
+    if (result.stripComments && patterns.openPattern && patterns.closePattern) {
+      cleanContents = result.updatedContents.replace(patterns.openPattern, '').replace(patterns.closePattern, '')
+    }
+    if (outputDir) {
+      // console.log(`- Update output file: ${outputPath}`)
+      await writeFile(outputPath, cleanContents)
+    }
+    if (!outputDir || applyTransformsToSource) {
+      // console.log(`- Update source file: ${srcPath}`)
+      await writeFile(srcPath, result.updatedContents)
+    }
+  }
+
+  return result
 }
 
 module.exports = {

package/lib/transforms/code.js

@@ -5,17 +5,40 @@ const { isLocalPath } = require('../utils/fs')
 const { deepLog } = require('../utils/logs')
 const { getLineCount, getTextBetweenLines } = require('../utils/text')
 
+/**
+ * Options for specifying source code to include in documentation.
+ * @typedef {Object} CodeTransformOptions
+ * @property {string} src - The relative path to the code to include, or the URL where the raw code lives.
+ * @property {string} [syntax] - The syntax of the code. If not specified, it will be inferred by fileType.
+ * @property {string} [header] - The header comment to add to the code snippet. Useful for pointing to relative source directory or adding live doc links.
+ * @property {string} [lines] - A range of lines of code to include from the file. The line range should be defined like "lines=22-44".
+ * @example
+   ```md
+   <!-- doc-gen CODE src="./relative/path/to/code.js" -->
+   This content will be dynamically replaced with code from the file
+   <!-- end-doc-gen -->
+   ```
+  
+   ```md
+   <!-- doc-gen 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 -->
+   ```
+ */
+
 // TODO code sections 
 // https://github.com/linear/linear/blob/94af540244864fbe466fb933256278e04e87513e/docs/transforms/code-section.js
 // https://github.com/linear/linear/blob/bc39d23af232f9fdbe7df458b0aaa9554ca83c57/packages/sdk/src/_tests/readme.test.ts#L133-L140
 // usage https://github.com/linear/linear/blame/93981d3a3db571e2f8efdce9f5271ea678941c43/packages/sdk/README.md#L1
 
 module.exports = function CODE(api) {
-  const { content, options, srcPath } = api
+  const { content, srcPath } = api
+  /** @type {CodeTransformOptions} */
+  const options = api.options || {}
   // console.log('CODE API', api)
   // process.exit(1)
   // console.log('options', options)
-  const { src, lines } = options
+  const { src, lines, id } = options
   const originalContent = content
   let code
   let syntax = options.syntax
@@ -28,6 +51,7 @@ module.exports = function CODE(api) {
     const fileDir = (srcPath) ? path.dirname(srcPath) : process.cwd()
     codeFilePath = path.resolve(fileDir, src)
     try {
+      // console.log('READFILE CODE', codeFilePath)
       code = fs.readFileSync(codeFilePath, 'utf8')
     } catch (e) {
       console.log(`FILE NOT FOUND ${codeFilePath}`)
@@ -70,19 +94,19 @@ module.exports = function CODE(api) {
   }
 
   /* Check for Id */
-  if (options.id) {
+  if (id) {
     const lines = code.split("\n")
-    const startLine = lines.findIndex(line => line.includes(`CODE_SECTION:${options.id}:START`)) ?? 0
-    const endLine = lines.findIndex(line => line.includes(`CODE_SECTION:${options.id}:END`)) ?? lines.length - 1
+    const startLine = lines.findIndex(line => line.includes(`CODE_SECTION:${id}:START`)) ?? 0
+    const endLine = lines.findIndex(line => line.includes(`CODE_SECTION:${id}:END`)) ?? lines.length - 1
     // console.log('startLine', startLine)
     // console.log('endLineendLine', endLine)
     if (startLine === -1 && endLine === -1) {
-      throw new Error(`Missing ${options.id} code section from ${codeFilePath}`)
+      throw new Error(`Missing ${id} code section from ${codeFilePath}`)
     }
   
-    const selectedLines = lines.slice(startLine + 1, endLine);
+    const selectedLines = lines.slice(startLine + 1, endLine)
   
-    const trimBy = selectedLines[0]?.match(/^(\s*)/)?.[1]?.length;
+    const trimBy = selectedLines[0]?.match(/^(\s*)/)?.[1]?.length
     const newValue = `${selectedLines.map(line => line.substring(trimBy).replace(/^\/\/ CODE_SECTION:INCLUDE /g, "")).join("\n")}`
     // console.log('newValue', newValue)
     code = newValue
@@ -96,8 +120,7 @@ module.exports = function CODE(api) {
     header = `\n${options.header}`
   }
 
-  return `<!-- The below code snippet is automatically added from ${src} -->
-\`\`\`${syntax}${header}
+  return `\`\`\`${syntax}${header}
 ${code}
 \`\`\``
 }

package/lib/transforms/file.js

@@ -5,8 +5,7 @@ const isLocalPath = require('is-local-path')
 module.exports = function FILE(api) {
   /*
   console.log('FILE API', api)
-  console.log(api.getBlockDetails())
-  process.exit(1)
+
   /** */
   const { options, srcPath } = api
   if (!options.src) {
@@ -17,6 +16,7 @@ module.exports = function FILE(api) {
     const fileDir = path.dirname(srcPath)
     const resolvedFilePath = path.resolve(fileDir, options.src)
     try {
+      // console.log('READFILE', resolvedFilePath)
       fileContents = fs.readFileSync(resolvedFilePath, 'utf8')
     } catch (e) {
       console.log(`FILE NOT FOUND ${resolvedFilePath}`)
@@ -27,6 +27,8 @@ module.exports = function FILE(api) {
   // trim leading and trailing spaces/line breaks in code and keeps the indentation of the first non-empty line
   fileContents = fileContents.replace(/^(?:[\t ]*(?:\r?\n|\r))+|\s+$/g, '')
 
+  return fileContents
+
   return `<!-- The below content is automatically added from ${options.src} -->
 ${fileContents}`
 }

package/lib/transforms/index.js

@@ -0,0 +1,114 @@
+const code = require('./code')
+const file = require('./file')
+const remoteContent = require('./remote')
+const toc = require('./toc')
+
+const transforms = {
+  /**
+   * ### > TOC
+   *
+   * Generate table of contents from markdown file
+   *
+   * **Options:**
+   * - `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 accordian. Default `false`
+   * - `collapseText` - *string* - (optional): Text the toc accordian summary
+   * - `excludeText` - *string* - (optional): Text to exclude in the table of contents. Default `Table of Contents`
+   * - `maxDepth` - *number* - (optional): Max depth of headings. Default 4
+   *
+   * **Example:**
+   * ```md
+   * <!-- doc-gen (TOC) -->
+   * toc will be generated here
+   * <!-- end-doc-gen -->
+   * ```
+   *
+   * Default `MATCHWORD` is `AUTO-GENERATED-CONTENT`
+   *
+   * ---
+   * @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
+   */
+  TOC: toc,
+  /**
+   * ### > CODE
+   *
+   * Get code from file or URL and put in markdown
+   *
+   * **Options:**
+   * - `src`: The relative path to the code to pull in, or the `URL` where the raw code lives
+   * - `syntax` (optional): Syntax will be inferred by fileType if not specified
+   * - `header` (optional): Will add header comment to code snippet. Useful for pointing to relative source directory or adding live doc links
+   * - `lines` (optional): a range with lines of code which will then be replaced with code from the file. The line range should be defined as: "lines=*startLine*-*EndLine*" (for example: "lines=22-44"). Please see the example below
+   *
+   * **Example:**
+   * ```md
+   * <!-- doc-gen (CODE:src=./relative/path/to/code.js) -->
+   * This content will be dynamically replaced with code from the file
+   * <!-- end-doc-gen -->
+   * ```
+   *
+   * ```md
+   *  <!-- doc-gen (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 -->
+   *  ```
+   * 
+   * Default `MATCHWORD` is `AUTO-GENERATED-CONTENT`
+   *
+   * ---
+   * @param {string} content The current content of the comment block
+   * @param {object} options The options passed in from the comment declaration
+   * @return {string} Updated inner contents of the comment block
+   */
+  CODE: code,
+  /**
+   * ### > FILE
+   *
+   * Get local file contents.
+   *
+   * **Options:**
+   * - `src`: The relative path to the file to pull in
+   *
+   * **Example:**
+   * ```md
+   * <!-- doc-gen (FILE:src=./path/to/file) -->
+   * This content will be dynamically replaced from the local file
+   * <!-- end-doc-gen -->
+   * ```
+   *
+   * Default `MATCHWORD` is `AUTO-GENERATED-CONTENT`
+   *
+   * ---
+   * @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
+   */
+  FILE: file,
+  /**
+   * ### > REMOTE
+   *
+   * Get any remote Data and put in markdown
+   *
+   * **Options:**
+   * - `url`: The URL of the remote content to pull in
+   *
+   * **Example:**
+   * ```md
+   * <!-- doc-gen (REMOTE:url=http://url-to-raw-md-file.md) -->
+   * This content will be dynamically replaced from the remote url
+   * <!-- end-doc-gen -->
+   * ```
+   *
+   * Default `MATCHWORD` is `AUTO-GENERATED-CONTENT`
+   *
+   * ---
+   * @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
+   */
+  REMOTE: remoteContent,
+}
+
+module.exports = transforms

package/lib/transforms/sectionToc.js

@@ -2,7 +2,7 @@ const { generateToc } = require('../utils/toc')
 
 module.exports = async function sectionToc(api) {
   // console.log("sectionToc", api)
-  const { options, fileContent, srcPath, getBlockDetails } = api
+  const { options, currentFileContent, srcPath, getBlockDetails } = api
   const opts = options || {}
   const subToc = await generateToc({
     options: {
@@ -10,7 +10,7 @@ module.exports = async function sectionToc(api) {
       // Set sub table of contents
       sub: true
     },
-    fileContent,
+    fileContent: currentFileContent,
     srcPath,
     getBlockDetails: getBlockDetails
   })

package/lib/transforms/toc.js

@@ -1,13 +1,31 @@
 const { generateToc } = require('../utils/toc')
 
+/**
+ * Options for configuring the table of contents.
+ * @typedef {Object} ToCTransformOptions
+ * @property {boolean} [firsth1=false] - Show the first h1 of the document in the table of contents. Default is `false`.
+ * @property {boolean} [collapse=false] - Collapse the table of contents in a detail accordion. Default is `false`.
+ * @property {string} [collapseText] - Text for the summary of the table of contents accordion.
+ * @property {string} [excludeText="Table of Contents"] - Text to exclude in the table of contents. Default is `Table of Contents`.
+ * @property {number} [maxDepth=4] - Maximum depth of headings to include in the table of contents. Default is `4`.
+ * @example
+   ```md
+   <!-- doc-gen (TOC) -->
+   toc will be generated here
+   <!-- end-doc-gen -->
+   ``` 
+ */
+
 module.exports = async function TOC(api) {
   // console.log("TOC API", api)
-  const { options, fileContent, srcPath, getBlockDetails } = api
+  const { currentFileContent, srcPath, getBlockDetails } = api
+  /** @type {ToCTransformOptions} */
+  const options = api.options || {}
   const toc = await generateToc({
-    options: options || {},
-    fileContent,
+    options,
     srcPath,
-    getBlockDetails: getBlockDetails
+    getBlockDetails: getBlockDetails,
+    fileContent: currentFileContent,
   })
   return toc
 }

package/lib/transforms/wordCount.js

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