@udx/mq 0.1.1

package/examples/make-collapsible.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+
+/**
+ * Example: Make Code Blocks Collapsible
+ * 
+ * This example demonstrates how to use mq to transform code blocks
+ * into collapsible sections.
+ */
+
+import { fromMarkdown } from 'mdast-util-from-markdown';
+import { toMarkdown } from 'mdast-util-to-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!';
+}
+\`\`\`
+`;
+
+// Parse markdown to AST
+const ast = fromMarkdown(markdown);
+
+// Clone the AST to avoid mutating the original
+const transformedAst = { ...ast };
+
+// Transform code blocks to collapsible sections
+visit(transformedAst, 'code', (node) => {
+  // Convert code node to HTML node with details/summary
+  node.type = 'html';
+  node.value = `<details>\n<summary>Click to view code example</summary>\n\n\`\`\`${node.lang || ''}\n${node.value}\`\`\`\n</details>`;
+  delete node.lang;
+});
+
+// Serialize back to markdown
+const result = toMarkdown(transformedAst);
+
+console.log('Original Markdown:');
+console.log('=================');
+console.log(markdown);
+console.log('\n');
+
+console.log('Transformed Markdown:');
+console.log('===================');
+console.log(result);
+
+// How to run this example:
+// node examples/make-collapsible.js

package/examples/query-headings.js

@@ -0,0 +1,56 @@
+/**
+ * Example: Query Headings
+ * 
+ * This example demonstrates how to use mdoc to query headings
+ * from markdown content.
+ */
+
+import { fromMarkdown } from 'mdast-util-from-markdown';
+import { visit } from 'unist-util-visit';
+import { toString } from 'mdast-util-to-string';
+
+// Example markdown content
+const markdown = `# Sample Documentation
+
+This is a sample documentation file to demonstrate heading queries.
+
+## Introduction
+
+This section introduces the topic.
+
+## Getting Started
+
+This section helps users get started.
+
+### Installation
+
+Installation instructions.
+
+### Configuration
+
+Configuration instructions.
+
+## Advanced Usage
+
+This section covers advanced usage scenarios.
+`;
+
+// Parse markdown to AST
+const ast = fromMarkdown(markdown);
+
+// Query all headings
+console.log('All headings:');
+console.log('============');
+visit(ast, 'heading', (node) => {
+  console.log(`${node.depth} ${toString(node)}`);
+});
+console.log('\n');
+
+// Query only h2 headings
+console.log('Only h2 headings:');
+console.log('===============');
+visit(ast, 'heading', (node) => {
+  if (node.depth === 2) {
+    console.log(toString(node));
+  }
+});

package/examples/toc-generator.js

@@ -0,0 +1,44 @@
+/**
+ * Example: TOC Generator
+ * 
+ * This example demonstrates how to use the mdoc TOC generation
+ * functionality to enhance markdown documentation.
+ */
+
+import { generateTOC } from '../index.js';
+
+// Example markdown content
+const markdown = `# Sample Documentation
+
+This is a sample documentation file to demonstrate TOC generation.
+
+## Introduction
+
+This section introduces the topic.
+
+## Getting Started
+
+This section helps users get started.
+
+## Advanced Usage
+
+This section covers advanced usage scenarios.
+
+## Troubleshooting
+
+This section helps users troubleshoot common issues.
+`;
+
+// Generate TOC with descriptive links
+const enhancedMarkdown = generateTOC(markdown, { 
+  descriptive: true 
+});
+
+console.log('Original Markdown:');
+console.log('=================');
+console.log(markdown);
+console.log('\n');
+
+console.log('Enhanced Markdown with TOC:');
+console.log('=========================');
+console.log(enhancedMarkdown);

package/lib/core.js

@@ -0,0 +1,347 @@
+/**
+ * Core utilities for markdown query and transform operations
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import { fromMarkdown } from 'mdast-util-from-markdown';
+import { toMarkdown } from 'mdast-util-to-markdown';
+import { toString } from 'mdast-util-to-string';
+import { visit } from 'unist-util-visit';
+import yaml from 'js-yaml';
+
+// Export all functions at the top for easier discovery
+export {
+  readStdin,
+  parseQuery,
+  filterNodes,
+  constructObject,
+  formatResult
+};
+
+export default {
+  readStdin,
+  parseQuery,
+  filterNodes,
+  constructObject,
+  formatResult
+};
+
+/**
+ * Read from stdin
+ * 
+ * @returns {Promise<string>} Content read from stdin
+ */
+async function readStdin() {
+  const chunks = [];
+  process.stdin.setEncoding('utf8');
+  
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  
+  return chunks.join('');
+}
+
+/**
+ * Parse a query into parts
+ * 
+ * Splits a query string by pipe character and trims each part.
+ * Used internally by queryMarkdown to break down complex queries.
+ * 
+ * @example
+ * Parse a simple query
+ * const parts = parseQuery('.headings[]');
+ * 
+ * @example
+ * Parse a complex query with pipes
+ * const parts = parseQuery('.headings[] | select(.level == 2) | {text}');
+ * 
+ * @param {string} query - Query string to parse
+ * @returns {Array} Array of query parts
+ */
+function parseQuery(query) {
+  if (!query) return [];
+  
+  // Handle edge case with escaped pipes
+  const parts = [];
+  let currentPart = '';
+  let inQuotes = false;
+  
+  for (let i = 0; i < query.length; i++) {
+    const char = query[i];
+    
+    if (char === '"' && (i === 0 || query[i-1] !== '\\')) {
+      inQuotes = !inQuotes;
+      currentPart += char;
+    } else if (char === '|' && !inQuotes) {
+      parts.push(currentPart.trim());
+      currentPart = '';
+    } else {
+      currentPart += char;
+    }
+  }
+  
+  if (currentPart.trim()) {
+    parts.push(currentPart.trim());
+  }
+  
+  return parts;
+}
+
+/**
+ * Filter nodes based on an expression
+ * 
+ * Filters an array of nodes based on a query expression. Supports various filtering operations
+ * including equality checks, contains, and startsWith.
+ * 
+ * @example
+ * Filter headings by level
+ * const level2Headings = filterNodes(headings, '.level == 2');
+ * 
+ * @example
+ * Filter links by URL pattern
+ * const externalLinks = filterNodes(links, '.href | startswith("https://")');
+ * 
+ * @example
+ * Filter links to specific domain
+ * const udxLinks = filterNodes(links, '.href | contains("udx.io")');
+ * 
+ * @param {Array} nodes - Array of nodes to filter
+ * @param {string} expr - Filter expression
+ * @returns {Array} Filtered array of nodes
+ */
+function filterNodes(nodes, expr) {
+  if (!expr.startsWith('select(')) return nodes;
+  
+  // Extract the condition from select()
+  const condition = expr.match(/select\((.*)\)/)?.[1];
+  if (!condition) return nodes;
+  
+  // Handle common filter patterns
+  if (condition.includes(' == ')) {
+    // Equality check: .prop == value
+    const [propPath, valueStr] = condition.split(' == ').map(s => s.trim());
+    const prop = propPath.startsWith('.') ? propPath.slice(1) : propPath;
+    
+    // Parse value (handle quoted strings)
+    let value;
+    if (valueStr.startsWith('"') && valueStr.endsWith('"')) {
+      value = valueStr.slice(1, -1);
+    } else if (valueStr === 'true' || valueStr === 'false') {
+      value = valueStr === 'true';
+    } else if (!isNaN(Number(valueStr))) {
+      value = Number(valueStr);
+    } else {
+      value = valueStr;
+    }
+    
+    // Apply filter
+    return nodes.filter(node => {
+      const propValue = prop.split('.').reduce((obj, p) => obj && obj[p], node);
+      
+      // Special case for filtering headings by level or undefined properties
+      if (propValue === undefined) {
+        return false; // Skip items with undefined properties
+      }
+      
+      return propValue === value;
+    });
+  } else if (condition.includes(' != ')) {
+    // Inequality check: .prop != value
+    const [propPath, valueStr] = condition.split(' != ').map(s => s.trim());
+    const prop = propPath.startsWith('.') ? propPath.slice(1) : propPath;
+    
+    // Parse value (handle quoted strings)
+    let value;
+    if (valueStr.startsWith('"') && valueStr.endsWith('"')) {
+      value = valueStr.slice(1, -1);
+    } else if (valueStr === 'true' || valueStr === 'false') {
+      value = valueStr === 'true';
+    } else if (!isNaN(Number(valueStr))) {
+      value = Number(valueStr);
+    } else {
+      value = valueStr;
+    }
+    
+    // Apply filter
+    return nodes.filter(node => {
+      const propValue = prop.split('.').reduce((obj, p) => obj && obj[p], node);
+      return propValue !== value;
+    });
+  } else if (condition.includes(' | contains(')) {
+    // Contains check: .prop | contains("value")
+    const [propPath, containsExpr] = condition.split(' | ').map(s => s.trim());
+    const prop = propPath.startsWith('.') ? propPath.slice(1) : propPath;
+    
+    // More robust regex to extract the value inside contains()
+    const valueMatch = containsExpr.match(/contains\(["]([^"]*)["]\)/);
+    const valueStr = valueMatch && valueMatch[1] ? valueMatch[1] : '';
+    
+    // Apply filter with improved error handling
+    return nodes.filter(node => {
+      try {
+        const propValue = prop.split('.').reduce((obj, p) => obj && obj[p] !== undefined ? obj[p] : null, node);
+        return propValue !== null && String(propValue).includes(valueStr);
+      } catch (err) {
+        // Silently skip items that cause errors
+        return false;
+      }
+    });
+  } else if (condition.includes(' | startswith(')) {
+    // StartsWith check: .prop | startswith("value")
+    const [propPath, startsWithExpr] = condition.split(' | ').map(s => s.trim());
+    const prop = propPath.startsWith('.') ? propPath.slice(1) : propPath;
+    const valueStr = startsWithExpr.match(/startswith\("(.*)"\)/)?.[1];
+    
+    if (!valueStr) return nodes;
+    
+    // Apply filter
+    return nodes.filter(node => {
+      const propValue = prop.split('.').reduce((obj, p) => obj && obj[p], node);
+      return typeof propValue === 'string' && propValue.startsWith(valueStr);
+    });
+  } else if (condition.includes(' > ') || condition.includes(' < ') || 
+             condition.includes(' >= ') || condition.includes(' <= ')) {
+    // Numeric comparison: .prop > value
+    let operator, parts;
+    if (condition.includes(' > ')) {
+      operator = '>';
+      parts = condition.split(' > ');
+    } else if (condition.includes(' < ')) {
+      operator = '<';
+      parts = condition.split(' < ');
+    } else if (condition.includes(' >= ')) {
+      operator = '>=';
+      parts = condition.split(' >= ');
+    } else if (condition.includes(' <= ')) {
+      operator = '<=';
+      parts = condition.split(' <= ');
+    }
+    
+    const [propPath, valueStr] = parts.map(s => s.trim());
+    const prop = propPath.startsWith('.') ? propPath.slice(1) : propPath;
+    const value = Number(valueStr);
+    
+    if (isNaN(value)) return nodes;
+    
+    // Apply filter
+    return nodes.filter(node => {
+      const propValue = prop.split('.').reduce((obj, p) => obj && obj[p], node);
+      switch (operator) {
+        case '>': return propValue > value;
+        case '<': return propValue < value;
+        case '>=': return propValue >= value;
+        case '<=': return propValue <= value;
+        default: return false;
+      }
+    });
+  }
+  
+  // Default: return unfiltered nodes
+  return nodes;
+}
+
+/**
+ * Construct an object from a pattern
+ * 
+ * Creates objects with specific properties from an array of nodes based on a pattern.
+ * Used internally by queryMarkdown to support object construction operations.
+ * 
+ * @example
+ * Extract only text and level properties from headings
+ * const headingInfo = constructObject(headings, '{text,level}');
+ * 
+ * @example
+ * Extract only href property from links
+ * const linkUrls = constructObject(links, '{href}');
+ * 
+ * @param {Array} nodes - Array of nodes to extract properties from
+ * @param {string} pattern - Pattern string in format '{prop1,prop2,...}'
+ * @returns {Array} Array of objects with specified properties
+ */
+function constructObject(nodes, pattern) {
+  if (!pattern.startsWith('{') || !pattern.endsWith('}')) return nodes;
+  
+  // Extract properties from pattern {prop1,prop2,...}
+  const propsStr = pattern.slice(1, -1);
+  const props = propsStr.split(',').map(p => p.trim());
+  
+  // Apply to each node
+  return nodes.map(node => {
+    const result = {};
+    props.forEach(prop => {
+      // Handle nested properties: 'meta.author'
+      if (prop.includes('.')) {
+        const parts = prop.split('.');
+        let value = node;
+        for (const part of parts) {
+          value = value && value[part];
+        }
+        result[prop] = value;
+      } else {
+        result[prop] = node[prop];
+      }
+    });
+    return result;
+  });
+}
+
+/**
+ * Format result based on specified format
+ * 
+ * @param {any} result - The result to format
+ * @param {string} format - Format to use (json, yaml, markdown)
+ * @returns {string} Formatted result
+ */
+function formatResult(result, format = 'markdown') {
+  try {
+    // Handle different types of results
+    if (typeof result === 'string') {
+      return result;
+    }
+    
+    // For empty results, return empty string
+    if (Array.isArray(result) && result.length === 0) {
+      return '';
+    }
+    
+    switch (format.toLowerCase()) {
+      case 'json':
+        return JSON.stringify(result, null, 2);
+      case 'yaml':
+        return yaml.dump(result);
+      case 'markdown':
+      default:
+        if (typeof result === 'object' && result.type === 'root') {
+          // If it's an AST, convert to markdown
+          return toMarkdown(result);
+        } else if (Array.isArray(result)) {
+          // If it's an array of AST nodes, convert each to markdown
+          if (result.some(item => item && item.type)) {
+            return result.map(node => {
+              if (node && node.type) {
+                // Handle single AST node
+                const tempAst = { type: 'root', children: [node] };
+                return toMarkdown(tempAst);
+              } else {
+                // Handle plain object
+                return JSON.stringify(node, null, 2);
+              }
+            }).join('\n\n');
+          } else {
+            // Regular array of objects
+            return JSON.stringify(result, null, 2);
+          }
+        } else {
+          // Default to JSON for other object types
+          return JSON.stringify(result, null, 2);
+        }
+    }
+  } catch (error) {
+    console.error('Error formatting result:', error);
+    return String(result);
+  }
+}
+
+// This default export is already declared at the top of the file

package/lib/integrations/mcurl.js

@@ -0,0 +1,125 @@
+/**
+ * mCurl integration utilities for Markdown Query
+ * 
+ * Provides functions for integrating mq with mcurl
+ */
+
+import { fromMarkdown } from 'mdast-util-from-markdown';
+import { toMarkdown } from 'mdast-util-to-markdown';
+import _ from 'lodash';
+import { queryMarkdown } from '../operations/query.js';
+import { transformMarkdown } from '../operations/transform.js';
+import { analyzeDocument } from '../operations/analysis.js';
+
+/**
+ * Main markdown handler for mCurl integration
+ * 
+ * Handles markdown content for mcurl integration, allowing mq queries,
+ * transformations, and analysis to be applied to fetched markdown content
+ * 
+ * @param {Object} response - Response object from mcurl
+ * @param {Object} options - Options object with mqQuery, mqTransform, and mqAnalyze properties
+ * @returns {string} Processed markdown content
+ */
+function markdownHandler(response, options) {
+  // Only process markdown content
+  if (!response.headers['content-type']?.includes('text/markdown') &&
+      !response.url?.endsWith('.md')) {
+    return response.body;
+  }
+  
+  // Get markdown content from response
+  const markdown = response.body;
+  
+  try {
+    // Parse markdown to AST
+    const ast = fromMarkdown(markdown);
+    
+    // Apply query if provided
+    if (options.mqQuery) {
+      const result = queryMarkdown(ast, options.mqQuery);
+      return formatResult(result, options.mqFormat || 'markdown');
+    }
+    
+    // Apply transform if provided
+    if (options.mqTransform) {
+      return transformMarkdown(ast, options.mqTransform);
+    }
+    
+    // Apply analysis if requested
+    if (options.mqAnalyze) {
+      return analyzeDocument(ast);
+    }
+    
+    // Return unchanged markdown if no operation specified
+    return markdown;
+  } catch (error) {
+    console.error(`Error processing markdown: ${error.message}`);
+    return markdown;
+  }
+}
+
+/**
+ * Register the markdown handler with mCurl
+ * 
+ * Registers the mq markdown handler with mcurl to enable processing
+ * of markdown content fetched by mcurl
+ * 
+ * @returns {boolean} True if registration successful, false otherwise
+ */
+function registerMarkdownHandler() {
+  try {
+    // Get mcurl module path
+    const mcurlPath = '../../mcurl/index.js';
+    
+    // Try to import mcurl
+    import(mcurlPath).then(mcurl => {
+      // Register handler
+      if (mcurl && mcurl.registerContentHandler) {
+        mcurl.registerContentHandler('text/markdown', markdownHandler);
+        mcurl.registerContentHandler('text/x-markdown', markdownHandler);
+        return true;
+      }
+      return false;
+    }).catch(error => {
+      console.error(`Error importing mcurl: ${error.message}`);
+      return false;
+    });
+  } catch (error) {
+    console.error(`Error registering markdown handler: ${error.message}`);
+    return false;
+  }
+}
+
+/**
+ * Format result based on specified format
+ * 
+ * @param {any} result - The result to format
+ * @param {string} format - Format to use (json, yaml, markdown)
+ * @returns {string} Formatted result
+ */
+function formatResult(result, format = 'markdown') {
+  switch (format.toLowerCase()) {
+    case 'json':
+      return JSON.stringify(result, null, 2);
+    case 'yaml':
+      return yaml.dump(result);
+    case 'markdown':
+    default:
+      if (typeof result === 'string') {
+        return result;
+      } else if (Array.isArray(result)) {
+        return result.map(item => 
+          typeof item === 'string' ? item : JSON.stringify(item, null, 2)
+        ).join('\n\n');
+      } else {
+        return JSON.stringify(result, null, 2);
+      }
+  }
+}
+
+export {
+  markdownHandler,
+  registerMarkdownHandler,
+  formatResult
+};