@udx/mq 0.1.1

package/examples/analyze-document.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+
+/**
+ * Example: Analyze Document Structure
+ * 
+ * This example demonstrates how to use mq to analyze the structure
+ * and content of a markdown document.
+ */
+
+import { fromMarkdown } from 'mdast-util-from-markdown';
+import { toString } from 'mdast-util-to-string';
+import { visit } from 'unist-util-visit';
+
+// Example markdown content
+const markdown = `# Architecture Overview
+
+## Introduction
+
+This document provides an overview of our system architecture.
+
+## Components
+
+### API Gateway
+
+The API Gateway handles all incoming requests.
+
+### Service Layer
+
+The Service Layer contains business logic.
+
+### Data Layer
+
+The Data Layer manages data persistence.
+
+## Deployment
+
+We use a CI/CD pipeline for deployment.
+
+## References
+
+- [AWS Documentation](https://aws.amazon.com/documentation/)
+- [Kubernetes](https://kubernetes.io/)
+- [Docker](https://www.docker.com/)
+`;
+
+// Parse markdown to AST
+const ast = fromMarkdown(markdown);
+
+// Analyze document structure
+function analyzeDocument(ast) {
+  let analysis = '# Document Analysis\n\n';
+  
+  // Count elements
+  const counts = {
+    headings: 0,
+    paragraphs: 0,
+    links: 0,
+    images: 0,
+    codeBlocks: 0,
+    lists: 0,
+    listItems: 0
+  };
+  
+  visit(ast, (node) => {
+    switch (node.type) {
+      case 'heading':
+        counts.headings++;
+        break;
+      case 'paragraph':
+        counts.paragraphs++;
+        break;
+      case 'link':
+        counts.links++;
+        break;
+      case 'image':
+        counts.images++;
+        break;
+      case 'code':
+        counts.codeBlocks++;
+        break;
+      case 'list':
+        counts.lists++;
+        break;
+      case 'listItem':
+        counts.listItems++;
+        break;
+    }
+  });
+  
+  // Add counts to analysis
+  analysis += '## Document Statistics\n\n';
+  Object.entries(counts).forEach(([key, value]) => {
+    analysis += `- **${key.charAt(0).toUpperCase() + key.slice(1)}**: ${value}\n`;
+  });
+  
+  // Analyze heading structure
+  analysis += '\n## Heading Structure\n\n';
+  
+  const headings = [];
+  visit(ast, 'heading', (node) => {
+    headings.push({
+      level: node.depth,
+      text: toString(node)
+    });
+  });
+  
+  headings.forEach(heading => {
+    const indent = '  '.repeat(heading.level - 1);
+    analysis += `${indent}- ${heading.text}\n`;
+  });
+  
+  // Analyze content distribution
+  analysis += '\n## Content Distribution\n\n';
+  
+  // Count words in each section
+  const sections = [];
+  let currentHeading = null;
+  let currentContent = '';
+  
+  visit(ast, (node) => {
+    if (node.type === 'heading') {
+      if (currentHeading) {
+        sections.push({
+          heading: currentHeading,
+          content: currentContent,
+          wordCount: currentContent.split(/\s+/).filter(Boolean).length
+        });
+      }
+      currentHeading = toString(node);
+      currentContent = '';
+    } else if (node.type === 'paragraph' || node.type === 'code') {
+      currentContent += toString(node) + ' ';
+    }
+  });
+  
+  // Add the last section
+  if (currentHeading) {
+    sections.push({
+      heading: currentHeading,
+      content: currentContent,
+      wordCount: currentContent.split(/\s+/).filter(Boolean).length
+    });
+  }
+  
+  // Sort sections by word count
+  sections.sort((a, b) => b.wordCount - a.wordCount);
+  
+  // Display section word counts
+  analysis += '| Section | Word Count |\n';
+  analysis += '| --- | --- |\n';
+  sections.forEach(section => {
+    analysis += `| ${section.heading} | ${section.wordCount} |\n`;
+  });
+  
+  // Analyze links
+  analysis += '\n## Links\n\n';
+  
+  const links = [];
+  visit(ast, 'link', (node) => {
+    links.push({
+      text: toString(node),
+      href: node.url
+    });
+  });
+  
+  if (links.length > 0) {
+    analysis += '| Text | URL |\n';
+    analysis += '| --- | --- |\n';
+    links.forEach(link => {
+      analysis += `| ${link.text} | ${link.href} |\n`;
+    });
+  } else {
+    analysis += 'No links found in the document.\n';
+  }
+  
+  return analysis;
+}
+
+const analysis = analyzeDocument(ast);
+
+console.log('Original Markdown:');
+console.log('=================');
+console.log(markdown);
+console.log('\n');
+
+console.log('Document Analysis:');
+console.log('=================');
+console.log(analysis);
+
+// How to run this example:
+// node examples/analyze-document.js

package/examples/cross-linker.js

@@ -0,0 +1,47 @@
+/**
+ * Example: Cross-Linker
+ * 
+ * This example demonstrates how to use the mdoc cross-linking
+ * functionality to add related document references.
+ */
+
+import { addCrossLinks } from '../index.js';
+
+// Example markdown content
+const markdown = `# Worker Architecture Documentation
+
+## Table of Contents
+1. [Introduction](#introduction)
+2. [Core Components](#core-components)
+3. [Implementation Guide](#implementation-guide)
+
+## Introduction
+
+This document describes the Worker architecture.
+
+## Core Components
+
+This section details the core components of the Worker architecture.
+
+## Implementation Guide
+
+This section provides a guide for implementing the Worker architecture.
+`;
+
+// Add cross-links to related documents
+const enhancedMarkdown = addCrossLinks(markdown, {
+  docs: [
+    { path: 'pipeline-as-code.md', description: 'Explore the deployment automation that integrates with Worker' },
+    { path: 'stateless.md', description: 'Learn how Worker enables stateless media management' },
+    { path: 'rabbit-ci.md', description: 'Understand the CI/CD platform that works with Worker' }
+  ]
+});
+
+console.log('Original Markdown:');
+console.log('=================');
+console.log(markdown);
+console.log('\n');
+
+console.log('Enhanced Markdown with Cross-Links:');
+console.log('================================');
+console.log(enhancedMarkdown);

package/examples/demo-architecture.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+
+/**
+ * mq - Architecture Files Demo
+ * 
+ * This script demonstrates using mq with architecture files from the content/architecture directory.
+ * 
+ * @todo move files being tested with into test/fixtures
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+
+const execAsync = promisify(exec);
+
+// Get the directory name
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const architectureDir = path.join(__dirname, '..', '..', 'content', 'architecture');
+const mqPath = path.join(__dirname, 'index.js');
+
+// Test cases for architecture files
+const TEST_CASES = [
+  {
+    name: 'Extract headings from pipeline-as-code.md',
+    command: `node ${mqPath} '.headings[]' -i ${path.join(architectureDir, 'pipeline-as-code.md')} | head -20`,
+    description: 'Extracts the first 20 headings from the pipeline-as-code.md file'
+  },
+  {
+    name: 'Generate TOC for data-discovery.md',
+    command: `node ${mqPath} '.toc' -i ${path.join(architectureDir, 'data-discovery.md')} | head -20`,
+    description: 'Generates a table of contents for the data-discovery.md file'
+  },
+  {
+    name: 'Count elements in content-website.md',
+    command: `node ${mqPath} --count -i ${path.join(architectureDir, 'content-website.md')}`,
+    description: 'Counts document elements in the content-website.md file'
+  },
+  {
+    name: 'Analyze document structure of wordpress-implementation.md',
+    command: `node ${mqPath} --structure -i ${path.join(architectureDir, 'wordpress-implementation.md')} | head -20`,
+    description: 'Shows the document structure of the wordpress-implementation.md file'
+  },
+  {
+    name: 'Extract code blocks from hoxler.md',
+    command: `node ${mqPath} '.codeBlocks[]' -i ${path.join(architectureDir, 'hoxler.md')} | head -20`,
+    description: 'Extracts code blocks from the hoxler.md file'
+  },
+  {
+    name: 'Extract links from transact-campus.md',
+    command: `node ${mqPath} '.links[]' -i ${path.join(architectureDir, 'transact-campus.md')} | head -20`,
+    description: 'Extracts links from the transact-campus.md file'
+  },
+  {
+    name: 'Full document analysis of worker.md',
+    command: `node ${mqPath} --analyze -i ${path.join(architectureDir, 'worker.md')} | head -40`,
+    description: 'Performs a full document analysis of the worker.md file'
+  }
+];
+
+// Run the demo
+async function runDemo() {
+  console.log('Running mq demo with architecture files...\n');
+  
+  for (const testCase of TEST_CASES) {
+    console.log(`\n=== ${testCase.name} ===`);
+    console.log(`Description: ${testCase.description}`);
+    console.log(`Command: ${testCase.command}`);
+    console.log('\nOutput:');
+    
+    try {
+      const { stdout, stderr } = await execAsync(testCase.command);
+      
+      if (stderr) {
+        console.error(`Error: ${stderr}`);
+        continue;
+      }
+      
+      console.log(stdout);
+    } catch (error) {
+      console.error(`Error running test "${testCase.name}":`, error.message);
+    }
+    
+    console.log('\n' + '-'.repeat(80));
+  }
+  
+  console.log('\nDemo completed successfully!');
+}
+
+// Run the demo
+runDemo();

package/examples/demo.js

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+
+/**
+ * mq - Markdown Query
+ * Demo script for testing with architecture files
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import { execSync } from 'child_process';
+
+// Main function
+async function main() {
+  console.log('=== MQ DEMO WITH ARCHITECTURE FILES ===\n');
+  
+  // Find markdown files in architecture directory
+  const architectureDir = path.join(process.cwd(), '../../content/architecture');
+  const files = await fs.readdir(architectureDir);
+  const markdownFiles = files.filter(file => file.endsWith('.md'));
+  
+  console.log(`Found ${markdownFiles.length} markdown files in content/architecture/\n`);
+  
+  // Select a file for demonstration
+  const demoFile = markdownFiles[0];
+  const demoFilePath = path.join(architectureDir, demoFile);
+  
+  console.log(`Demonstrating mq with ${demoFile}:\n`);
+  
+  // Demo 1: Extract headings
+  console.log('=== DEMO 1: EXTRACT HEADINGS ===');
+  console.log(`Command: cat ${demoFilePath} | mq '.headings[]'`);
+  console.log();
+  
+  try {
+    const headingsOutput = execSync(`cat ${demoFilePath} | node ${path.join(process.cwd(), 'index.js')} '.headings[]'`).toString();
+    const headings = headingsOutput.split('\n').filter(Boolean);
+    
+    // Show first few headings
+    const headingsToShow = Math.min(5, headings.length);
+    for (let i = 0; i < headingsToShow; i++) {
+      console.log(headings[i]);
+    }
+    
+    if (headings.length > headingsToShow) {
+      console.log(`... and ${headings.length - headingsToShow} more headings\n`);
+    }
+  } catch (error) {
+    console.error(`Error extracting headings: ${error.message}`);
+  }
+  
+  // Demo 2: Generate TOC
+  console.log('=== DEMO 2: GENERATE TABLE OF CONTENTS ===');
+  console.log(`Command: cat ${demoFilePath} | mq '.toc'`);
+  console.log();
+  
+  try {
+    const tocOutput = execSync(`cat ${demoFilePath} | node ${path.join(process.cwd(), 'index.js')} '.toc'`).toString();
+    const tocLines = tocOutput.split('\n').filter(Boolean);
+    
+    // Show first few TOC lines
+    const linesToShow = Math.min(10, tocLines.length);
+    for (let i = 0; i < linesToShow; i++) {
+      console.log(tocLines[i]);
+    }
+    
+    if (tocLines.length > linesToShow) {
+      console.log('...\n');
+    }
+  } catch (error) {
+    console.error(`Error generating TOC: ${error.message}`);
+  }
+  
+  // Demo 3: Count document elements
+  console.log('=== DEMO 3: COUNT DOCUMENT ELEMENTS ===');
+  console.log(`Command: cat ${demoFilePath} | mq --count`);
+  console.log();
+  
+  try {
+    const countOutput = execSync(`cat ${demoFilePath} | node ${path.join(process.cwd(), 'index.js')} --count`).toString();
+    console.log(countOutput);
+  } catch (error) {
+    console.error(`Error counting elements: ${error.message}`);
+  }
+  
+  // Demo 4: Extract code blocks
+  console.log('=== DEMO 4: EXTRACT CODE BLOCKS ===');
+  console.log(`Command: cat ${demoFilePath} | mq '.codeBlocks[]'`);
+  console.log();
+  
+  try {
+    const codeBlocksOutput = execSync(`cat ${demoFilePath} | node ${path.join(process.cwd(), 'index.js')} '.codeBlocks[]'`).toString();
+    const codeBlocks = codeBlocksOutput.split('\n\n').filter(block => block.trim().startsWith('{'));
+    
+    // Show first code block
+    if (codeBlocks.length > 0) {
+      console.log(codeBlocks[0]);
+      
+      if (codeBlocks.length > 1) {
+        console.log(`... and ${codeBlocks.length - 1} more code blocks\n`);
+      }
+    } else {
+      console.log('No code blocks found in the document.\n');
+    }
+  } catch (error) {
+    console.error(`Error extracting code blocks: ${error.message}`);
+  }
+  
+  // Demo 5: Transform code blocks to collapsible
+  console.log('=== DEMO 5: TRANSFORM CODE BLOCKS TO COLLAPSIBLE ===');
+  console.log(`Command: cat ${demoFilePath} | mq --transform '.codeBlocks[] |= makeCollapsible'`);
+  console.log();
+  
+  try {
+    const transformOutput = execSync(`cat ${demoFilePath} | node ${path.join(process.cwd(), 'index.js')} --transform '.codeBlocks[] |= makeCollapsible'`).toString();
+    const transformLines = transformOutput.split('\n');
+    
+    // Find the first transformed code block
+    let detailsStartIndex = -1;
+    for (let i = 0; i < transformLines.length; i++) {
+      if (transformLines[i].includes('<details>')) {
+        detailsStartIndex = i;
+        break;
+      }
+    }
+    
+    if (detailsStartIndex >= 0) {
+      // Show the transformed code block
+      for (let i = detailsStartIndex; i < Math.min(detailsStartIndex + 10, transformLines.length); i++) {
+        console.log(transformLines[i]);
+      }
+      console.log('...\n');
+    } else {
+      console.log('No code blocks found to transform.\n');
+    }
+  } catch (error) {
+    console.error(`Error transforming code blocks: ${error.message}`);
+  }
+  
+  // Demo 6: Analyze document structure
+  console.log('=== DEMO 6: ANALYZE DOCUMENT STRUCTURE ===');
+  console.log(`Command: cat ${demoFilePath} | mq --analyze`);
+  console.log();
+  
+  try {
+    const analyzeOutput = execSync(`cat ${demoFilePath} | node ${path.join(process.cwd(), 'index.js')} --analyze`).toString();
+    const analyzeLines = analyzeOutput.split('\n');
+    
+    // Show the first part of the analysis
+    for (let i = 0; i < Math.min(20, analyzeLines.length); i++) {
+      console.log(analyzeLines[i]);
+    }
+    
+    if (analyzeLines.length > 20) {
+      console.log('...\n');
+    }
+  } catch (error) {
+    console.error(`Error analyzing document: ${error.message}`);
+  }
+  
+  // Demo 7: Filter headings by level
+  console.log('=== DEMO 7: FILTER HEADINGS BY LEVEL ===');
+  console.log(`Command: cat ${demoFilePath} | mq '.headings[] | select(.level == 2)'`);
+  console.log();
+  
+  try {
+    const filterOutput = execSync(`cat ${demoFilePath} | node ${path.join(process.cwd(), 'index.js')} '.headings[] | select(.level == 2)'`).toString();
+    const filterHeadings = filterOutput.split('\n\n').filter(Boolean);
+    
+    // Show first few filtered headings
+    const headingsToShow = Math.min(5, filterHeadings.length);
+    for (let i = 0; i < headingsToShow; i++) {
+      console.log(filterHeadings[i]);
+    }
+    
+    if (filterHeadings.length > headingsToShow) {
+      console.log(`... and ${filterHeadings.length - headingsToShow} more level 2 headings\n`);
+    }
+  } catch (error) {
+    console.error(`Error filtering headings: ${error.message}`);
+  }
+  
+  // Summary
+  console.log('\n=== MQ USAGE SUMMARY ===');
+  console.log('After installing the mq package, you can use these commands:');
+  console.log('- Extract headings: mq \'.headings[]\'');
+  console.log('- Generate TOC: mq \'.toc\'');
+  console.log('- Count elements: mq --count');
+  console.log('- Show structure: mq --structure');
+  console.log('- Analyze document: mq --analyze');
+  console.log('- Transform code blocks: mq --transform \'.codeBlocks[] |= makeCollapsible\'');
+  console.log('- Filter headings: mq \'.headings[] | select(.level == 2)\'');
+  console.log('- Extract links: mq \'.links[]\'');
+  console.log('- Find external links: mq \'.links[] | select(.href | startswith("http"))\'');
+}
+
+// Run the main function
+main().catch(error => {
+  console.error('Error:', error.message);
+  process.exit(1);
+});

package/examples/filter-code-blocks.js

@@ -0,0 +1,64 @@
+/**
+ * Example: Filter Code Blocks
+ * 
+ * This example demonstrates how to use mdoc to filter code blocks
+ * by language.
+ */
+
+import { fromMarkdown } from 'mdast-util-from-markdown';
+import { visit } from 'unist-util-visit';
+
+// Example markdown content
+const markdown = `# Code Examples
+
+## JavaScript
+
+\`\`\`javascript
+function hello() {
+  console.log('Hello, world!');
+}
+\`\`\`
+
+## PHP
+
+\`\`\`php
+function hello() {
+  echo 'Hello, world!';
+}
+\`\`\`
+
+## Python
+
+\`\`\`python
+def hello():
+  print('Hello, world!')
+\`\`\`
+
+## Shell
+
+\`\`\`bash
+echo 'Hello, world!'
+\`\`\`
+`;
+
+// Parse markdown to AST
+const ast = fromMarkdown(markdown);
+
+// Extract all code blocks
+console.log('All code blocks:');
+console.log('==============');
+visit(ast, 'code', (node) => {
+  console.log(`Language: ${node.lang || 'none'}`);
+  console.log(node.value);
+  console.log('---');
+});
+console.log('\n');
+
+// Filter code blocks by language
+console.log('Only JavaScript code blocks:');
+console.log('=========================');
+visit(ast, 'code', (node) => {
+  if (node.lang === 'javascript') {
+    console.log(node.value);
+  }
+});

package/examples/generate-toc.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+
+/**
+ * Example: Generate Table of Contents
+ * 
+ * This example demonstrates how to use mq to generate a table of contents
+ * from a markdown document.
+ */
+
+import { fromMarkdown } from 'mdast-util-from-markdown';
+import { toString } from 'mdast-util-to-string';
+import { visit } from 'unist-util-visit';
+
+// Example markdown content
+const markdown = `# Architecture Documentation
+
+## Overview
+
+This document provides an overview of the architecture.
+
+## Components
+
+### Frontend
+
+The frontend is built with React.
+
+### Backend
+
+The backend is built with Node.js.
+
+### Database
+
+We use PostgreSQL for data storage.
+
+## Deployment
+
+Deployment is handled through CI/CD pipelines.
+`;
+
+// Parse markdown to AST
+const ast = fromMarkdown(markdown);
+
+// Extract headings
+const headings = [];
+visit(ast, 'heading', (node) => {
+  if (node.depth <= 3) { // Only include h1, h2, h3
+    headings.push({
+      level: node.depth,
+      text: toString(node),
+      anchor: toString(node).toLowerCase().replace(/[^\w]+/g, '-')
+    });
+  }
+});
+
+// Generate TOC
+const toc = headings.map((heading, index) => {
+  const indent = '  '.repeat(heading.level - 1);
+  return `${indent}${index + 1}. [${heading.text}](#${heading.anchor})`;
+}).join('\n');
+
+console.log('Original Markdown:');
+console.log('=================');
+console.log(markdown);
+console.log('\n');
+
+console.log('Generated Table of Contents:');
+console.log('==========================');
+console.log(toc);
+
+// How to run this example:
+// node examples/generate-toc.js