feat: add assemble command to reassemble exploded markdown documents

## CHANGES

- Add new `assemble` command to CLI
- Create `assembleDocument` method for reassembly
- Add `incrementHeadingLevels` helper method
- Add `extractSectionFilesFromTOC` to parse TOC
- Rename `explode-doc` command to `explode`
- Update help text and examples
- Bump version to 1.3.0
- Add comprehensive tests for workflow

Author: ksylvan

bin/md-tree.js

@@ -69,28 +69,30 @@ class MarkdownCLI {
 Usage: md-tree <command> <file> [options]
 
 Commands:
-  list <file>                      List all headings in the file
-  extract <file> <heading>         Extract a specific section by heading text
-  extract-all <file> [level]       Extract all sections at level (default: 2)
-  explode-doc <file> <output-dir>  Extract all level 2 sections and create index
-  tree <file>                      Show the document structure as a tree
-  search <file> <selector>         Search using CSS-like selectors
-  stats <file>                     Show document statistics
-  toc <file>                       Generate table of contents
-  version                          Show version information
-  help                             Show this help message
+  list <file>                   List all headings in the file
+  extract <file> <heading>      Extract a specific section by heading text
+  extract-all <file> [level]    Extract all sections at level (default: 2)
+  explode <file> <output-dir>   Extract all level 2 sections and create index
+  assemble <dir> <output-file>  Reassemble exploded document from directory
+  tree <file>                   Show the document structure as a tree
+  search <file> <selector>      Search using CSS-like selectors
+  stats <file>                  Show document statistics
+  toc <file>                    Generate table of contents
+  version                       Show version information
+  help                          Show this help message
 
 Options:
-  --output, -o <dir>              Output directory for extracted files
-  --level, -l <number>            Heading level to work with
-  --format, -f <json|text>        Output format (default: text)
-  --max-level <number>            Maximum heading level for TOC (default: 3)
+  --output, -o <dir>            Output directory for extracted files
+  --level, -l <number>          Heading level to work with
+  --format, -f <json|text>      Output format (default: text)
+  --max-level <number>          Maximum heading level for TOC (default: 3)
 
 Examples:
   md-tree list README.md
   md-tree extract README.md "Installation"
   md-tree extract-all README.md 2 --output ./sections
-  md-tree explode-doc README.md ./exploded
+  md-tree explode README.md ./exploded
+  md-tree assemble ./exploded reassembled.md
   md-tree tree README.md
   md-tree search README.md "heading[depth=2]"
   md-tree stats README.md
@@ -389,17 +391,28 @@ For more information, visit: https://github.com/ksylvan/markdown-tree-parser
           break;
         }
 
-        case 'explode-doc': {
+        case 'explode': {
           if (args.length < 3) {
             console.error(
-              '❌ Usage: md-tree explode-doc <file> <output-directory>'
+              '❌ Usage: md-tree explode <file> <output-directory>'
             );
             process.exit(1);
           }
           await this.explodeDocument(args[1], args[2]);
           break;
         }
 
+        case 'assemble': {
+          if (args.length < 3) {
+            console.error(
+              '❌ Usage: md-tree assemble <directory> <output-file>'
+            );
+            process.exit(1);
+          }
+          await this.assembleDocument(args[1], args[2]);
+          break;
+        }
+
         case 'tree':
           if (args.length < 2) {
             console.error('❌ Usage: md-tree tree <file>');
@@ -601,8 +614,129 @@ For more information, visit: https://github.com/ksylvan/markdown-tree-parser
 
     return clonedTree;
   }
+
+  // Helper method to increment all heading levels in a tree by 1
+  incrementHeadingLevels(tree) {
+    if (!tree || !tree.children) return tree;
+
+    // Create a deep copy to avoid modifying the original tree
+    const clonedTree = JSON.parse(JSON.stringify(tree));
+
+    const incrementNode = (node) => {
+      if (node.type === 'heading' && node.depth < 6) {
+        node.depth = node.depth + 1;
+      }
+
+      if (node.children) {
+        node.children.forEach(incrementNode);
+      }
+    };
+
+    if (clonedTree.children) {
+      clonedTree.children.forEach(incrementNode);
+    }
+
+    return clonedTree;
+  }
+
+  async assembleDocument(inputDir, outputFile) {
+    const indexPath = path.join(inputDir, 'index.md');
+
+    // Check if index.md exists
+    try {
+      await fs.access(indexPath);
+    } catch (_error) {
+      console.error(`❌ index.md not found in ${inputDir}`);
+      process.exit(1);
+    }
+
+    const indexContent = await this.readFile(indexPath);
+    const indexTree = await this.parser.parse(indexContent);
+
+    // Extract the main title and get the list of section files from TOC
+    const headings = this.parser.getHeadingsList(indexTree);
+    const mainTitle = headings.find((h) => h.level === 1);
+
+    if (!mainTitle) {
+      console.error('❌ No main title found in index.md');
+      process.exit(1);
+    }
+
+    console.log(`\n📚 Assembling document: ${mainTitle.text}`);
+
+    // Parse the TOC to extract section file references
+    const sectionFiles = await this.extractSectionFilesFromTOC(indexTree);
+
+    if (sectionFiles.length === 0) {
+      console.error('❌ No section files found in TOC');
+      process.exit(1);
+    }
+
+    console.log(`📖 Found ${sectionFiles.length} sections to assemble`);
+
+    // Start building the reassembled document
+    let assembledContent = `# ${mainTitle.text}\n\n`;
+
+    // Process each section file
+    for (const sectionFile of sectionFiles) {
+      console.log(`✅ Processing ${sectionFile.filename}...`);
+
+      const filePath = path.join(inputDir, sectionFile.filename);
+      try {
+        const sectionContent = await this.readFile(filePath);
+        const sectionTree = await this.parser.parse(sectionContent);
+
+        // Increment heading levels by 1 to restore original structure
+        const adjustedTree = this.incrementHeadingLevels(sectionTree);
+        const sectionMarkdown = await this.parser.stringify(adjustedTree);
+
+        // Remove the leading heading since it will be a level 2 now
+        assembledContent += sectionMarkdown + '\n\n';
+      } catch (_error) {
+        console.error(
+          `⚠️  Warning: Could not read ${sectionFile.filename}, skipping...`
+        );
+      }
+    }
+
+    // Write the assembled document
+    await this.writeFile(outputFile, assembledContent.trim());
+    console.log(`\n✨ Document assembled to ${outputFile}`);
+  }
+
+  async extractSectionFilesFromTOC(indexTree) {
+    // Convert the tree back to markdown to parse the TOC links
+    const indexMarkdown = await this.parser.stringify(indexTree);
+    const lines = indexMarkdown.split('\n');
+
+    const sectionFiles = [];
+    const processedFiles = new Set();
+
+    for (const line of lines) {
+      // Look for TOC lines that reference files (not just anchors)
+      const match = line.match(/\[([^\]]+)\]\(\.\/([^#)]+)(?:#[^)]*)?\)/);
+      if (match) {
+        const [, linkText, filename] = match;
+
+        // Only include level 2 sections (main sections, not sub-sections)
+        // Level 2 items have exactly 2 spaces before the dash (are children of main heading)
+        // Level 3+ items have 4+ spaces (are nested deeper)
+        if (line.match(/^ {2}[-*] \[/) && !processedFiles.has(filename)) {
+          sectionFiles.push({
+            filename,
+            title: linkText,
+          });
+          processedFiles.add(filename);
+        }
+      }
+    }
+
+    return sectionFiles;
+  }
 }
 
-// Run CLI
+// Export the class for testing
+export { MarkdownCLI };
+
 const cli = new MarkdownCLI();
 cli.run();

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@kayvan/markdown-tree-parser",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "A powerful JavaScript library and CLI tool for parsing and manipulating markdown files as tree structures using the remark/unified ecosystem",
   "type": "module",
   "main": "index.js",

package.json

@@ -155,10 +155,10 @@ async function runTests() {
 
   const testFile = await setupTests();
 
-  // Test explode-doc command
-  await test('CLI explode-doc command', async () => {
+  // Test explode command
+  await test('CLI explode command', async () => {
     const outputDir = path.join(testDir, 'exploded');
-    const result = await runCLI(['explode-doc', testFile, outputDir]);
+    const result = await runCLI(['explode', testFile, outputDir]);
 
     assert(
       result.code === 0,
@@ -189,7 +189,7 @@ async function runTests() {
     );
   });
 
-  await test('CLI explode-doc index.md content', async () => {
+  await test('CLI explode index.md content', async () => {
     const outputDir = path.join(testDir, 'exploded');
     const indexPath = path.join(outputDir, 'index.md');
     const indexContent = await fs.readFile(indexPath, 'utf-8');
@@ -236,7 +236,7 @@ async function runTests() {
     );
   });
 
-  await test('CLI explode-doc individual files', async () => {
+  await test('CLI explode individual files', async () => {
     const outputDir = path.join(testDir, 'exploded');
 
     // Check introduction.md
@@ -276,34 +276,31 @@ async function runTests() {
     );
   });
 
-  await test('CLI explode-doc error handling', async () => {
+  await test('CLI explode error handling', async () => {
     // Test with non-existent file
-    const result = await runCLI(['explode-doc', 'non-existent.md', testDir]);
+    const result = await runCLI(['explode', 'non-existent.md', testDir]);
     assert(result.code !== 0, 'Should fail with non-existent file');
     assert(
       result.stderr.includes('Error reading file'),
       'Should show error message'
     );
   });
 
-  await test('CLI explode-doc usage help', async () => {
+  await test('CLI explode usage help', async () => {
     // Test with missing arguments
-    const result = await runCLI(['explode-doc']);
+    const result = await runCLI(['explode']);
     assert(result.code !== 0, 'Should fail with missing arguments');
     assert(
-      result.stderr.includes('Usage: md-tree explode-doc'),
+      result.stderr.includes('Usage: md-tree explode'),
       'Should show usage message'
     );
   });
 
-  // Test that help includes explode-doc
-  await test('CLI help includes explode-doc', async () => {
+  // Test that help includes explode
+  await test('CLI help includes explode', async () => {
     const result = await runCLI(['help']);
     assert(result.code === 0, 'Help command should succeed');
-    assert(
-      result.stdout.includes('explode-doc'),
-      'Help should mention explode-doc'
-    );
+    assert(result.stdout.includes('explode'), 'Help should mention explode');
     assert(
       result.stdout.includes('Extract all level 2 sections and create index'),
       'Should have description'