mrmd-js 2.0.0

package/src/transform/async.js

@@ -0,0 +1,133 @@
+/**
+ * Async Transform
+ *
+ * Wraps code to support top-level await.
+ * @module transform/async
+ */
+
+/**
+ * Check if code contains top-level await
+ * @param {string} code
+ * @returns {boolean}
+ */
+function hasTopLevelAwait(code) {
+  // Simple check - look for await outside of async function/arrow
+  // This is a heuristic; a proper check would need AST parsing
+
+  // Remove strings, comments, and regex to avoid false positives
+  const cleaned = code
+    // Remove template literals (simple version)
+    .replace(/`[^`]*`/g, '')
+    // Remove strings
+    .replace(/"(?:[^"\\]|\\.)*"/g, '')
+    .replace(/'(?:[^'\\]|\\.)*'/g, '')
+    // Remove single-line comments
+    .replace(/\/\/[^\n]*/g, '')
+    // Remove multi-line comments
+    .replace(/\/\*[\s\S]*?\*\//g, '');
+
+  // Track nesting depth of async contexts
+  // This is simplified - real implementation would use AST
+  let depth = 0;
+  let i = 0;
+
+  while (i < cleaned.length) {
+    // Check for async function or async arrow
+    if (cleaned.slice(i, i + 5) === 'async') {
+      // Look ahead for function or arrow
+      let j = i + 5;
+      while (j < cleaned.length && /\s/.test(cleaned[j])) j++;
+
+      if (
+        cleaned.slice(j, j + 8) === 'function' ||
+        cleaned[j] === '('
+      ) {
+        // Found async context start
+        depth++;
+      }
+    }
+
+    // Track braces for context depth (simplified)
+    if (cleaned[i] === '{') {
+      // Already in async context, depth increases
+    }
+    if (cleaned[i] === '}') {
+      // Could be end of async context
+      if (depth > 0) depth--;
+    }
+
+    // Check for await at top level
+    if (cleaned.slice(i, i + 5) === 'await') {
+      const before = i > 0 ? cleaned[i - 1] : ' ';
+      const after = i + 5 < cleaned.length ? cleaned[i + 5] : ' ';
+
+      // Check it's a word boundary
+      if (!/[a-zA-Z0-9_$]/.test(before) && !/[a-zA-Z0-9_$]/.test(after)) {
+        // Found await - check if we're at top level
+        // For simplicity, assume any await not deep in braces is top-level
+        // A proper implementation would track async function scopes
+        return true;
+      }
+    }
+
+    i++;
+  }
+
+  return false;
+}
+
+/**
+ * Wrap code for top-level await support
+ *
+ * Transforms code to run in an async IIFE that captures the last expression.
+ *
+ * @param {string} code - Source code
+ * @returns {string} Wrapped code
+ */
+export function wrapForAsync(code) {
+  const needsAsync = hasTopLevelAwait(code);
+
+  // We always wrap to capture the return value
+  // The wrapper captures the last expression value
+
+  if (needsAsync) {
+    return `(async () => {
+${code}
+})()`;
+  }
+
+  return `(() => {
+${code}
+})()`;
+}
+
+/**
+ * Wrap code and capture the last expression value
+ *
+ * @param {string} code - Source code
+ * @returns {string} Wrapped code that returns last expression
+ */
+export function wrapWithLastExpression(code) {
+  const needsAsync = hasTopLevelAwait(code);
+
+  // Find the last expression and make it a return value
+  // This is tricky without AST - we use eval trick instead
+  const wrapped = `
+;(${needsAsync ? 'async ' : ''}function() {
+  let __result__;
+  try {
+    __result__ = eval(${JSON.stringify(code)});
+  } catch (e) {
+    if (e instanceof SyntaxError) {
+      // Code might be statements, not expression
+      eval(${JSON.stringify(code)});
+      __result__ = undefined;
+    } else {
+      throw e;
+    }
+  }
+  return __result__;
+})()`;
+
+  return wrapped.trim();
+}

package/src/transform/extract.js

@@ -0,0 +1,251 @@
+/**
+ * Extract Transform
+ *
+ * Extracts declared variable names from code.
+ * @module transform/extract
+ */
+
+/**
+ * Extract all variable names that will be declared by the code.
+ * Handles var, let, const, function, and class declarations.
+ *
+ * @param {string} code - Source code
+ * @returns {string[]} Array of declared variable names
+ *
+ * @example
+ * extractDeclaredVariables('const x = 1; let { a, b } = obj; function foo() {}')
+ * // Returns: ['x', 'a', 'b', 'foo']
+ */
+export function extractDeclaredVariables(code) {
+  const variables = new Set();
+
+  // Remove strings, comments to avoid false matches
+  const cleaned = removeStringsAndComments(code);
+
+  // Match var/let/const declarations
+  // Handles: const x = 1, let x = 1, var x = 1
+  // Handles: const { a, b } = obj, const [a, b] = arr
+  const varPattern = /\b(?:var|let|const)\s+([^=;]+?)(?:\s*=|\s*;|\s*$)/g;
+
+  let match;
+  while ((match = varPattern.exec(cleaned)) !== null) {
+    const declaration = match[1].trim();
+    extractNamesFromPattern(declaration, variables);
+  }
+
+  // Match function declarations
+  const funcPattern = /\bfunction\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\(/g;
+  while ((match = funcPattern.exec(cleaned)) !== null) {
+    variables.add(match[1]);
+  }
+
+  // Match class declarations
+  const classPattern = /\bclass\s+([a-zA-Z_$][a-zA-Z0-9_$]*)/g;
+  while ((match = classPattern.exec(cleaned)) !== null) {
+    variables.add(match[1]);
+  }
+
+  return Array.from(variables);
+}
+
+/**
+ * Extract variable names from a destructuring pattern or simple identifier
+ * @param {string} pattern
+ * @param {Set<string>} variables
+ */
+function extractNamesFromPattern(pattern, variables) {
+  // Simple identifier
+  const simpleMatch = pattern.match(/^([a-zA-Z_$][a-zA-Z0-9_$]*)$/);
+  if (simpleMatch) {
+    variables.add(simpleMatch[1]);
+    return;
+  }
+
+  // Object destructuring { a, b: c, ...rest }
+  if (pattern.startsWith('{')) {
+    const inner = pattern.slice(1, -1);
+    // Split by comma, handling nested braces
+    const parts = splitByComma(inner);
+    for (const part of parts) {
+      const trimmed = part.trim();
+      if (!trimmed) continue;
+
+      // Handle rest: ...rest
+      if (trimmed.startsWith('...')) {
+        const name = trimmed.slice(3).trim();
+        if (isValidIdentifier(name)) {
+          variables.add(name);
+        }
+        continue;
+      }
+
+      // Handle rename: key: name or key: pattern
+      const colonIdx = trimmed.indexOf(':');
+      if (colonIdx !== -1) {
+        const value = trimmed.slice(colonIdx + 1).trim();
+        extractNamesFromPattern(value, variables);
+      } else {
+        // Simple: key (which is also the variable name)
+        const name = trimmed.split('=')[0].trim(); // Handle default values
+        if (isValidIdentifier(name)) {
+          variables.add(name);
+        }
+      }
+    }
+    return;
+  }
+
+  // Array destructuring [a, b, ...rest]
+  if (pattern.startsWith('[')) {
+    const inner = pattern.slice(1, -1);
+    const parts = splitByComma(inner);
+    for (const part of parts) {
+      const trimmed = part.trim();
+      if (!trimmed) continue;
+
+      // Handle rest: ...rest
+      if (trimmed.startsWith('...')) {
+        const name = trimmed.slice(3).trim();
+        if (isValidIdentifier(name)) {
+          variables.add(name);
+        }
+        continue;
+      }
+
+      // Handle nested destructuring or simple name
+      const nameOrPattern = trimmed.split('=')[0].trim();
+      extractNamesFromPattern(nameOrPattern, variables);
+    }
+    return;
+  }
+
+  // Multiple declarations: a, b, c (from var a, b, c)
+  if (pattern.includes(',')) {
+    const parts = splitByComma(pattern);
+    for (const part of parts) {
+      const trimmed = part.trim().split('=')[0].trim();
+      if (isValidIdentifier(trimmed)) {
+        variables.add(trimmed);
+      }
+    }
+  }
+}
+
+/**
+ * Split string by commas, respecting nested brackets
+ * @param {string} str
+ * @returns {string[]}
+ */
+function splitByComma(str) {
+  const parts = [];
+  let current = '';
+  let depth = 0;
+
+  for (const char of str) {
+    if ((char === '{' || char === '[' || char === '(')) {
+      depth++;
+      current += char;
+    } else if ((char === '}' || char === ']' || char === ')')) {
+      depth--;
+      current += char;
+    } else if (char === ',' && depth === 0) {
+      parts.push(current);
+      current = '';
+    } else {
+      current += char;
+    }
+  }
+
+  if (current) {
+    parts.push(current);
+  }
+
+  return parts;
+}
+
+/**
+ * Check if string is a valid JavaScript identifier
+ * @param {string} name
+ * @returns {boolean}
+ */
+function isValidIdentifier(name) {
+  return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name);
+}
+
+/**
+ * Remove strings and comments from code
+ * @param {string} code
+ * @returns {string}
+ */
+function removeStringsAndComments(code) {
+  let result = '';
+  let i = 0;
+
+  while (i < code.length) {
+    // Single-line comment
+    if (code[i] === '/' && code[i + 1] === '/') {
+      while (i < code.length && code[i] !== '\n') i++;
+      continue;
+    }
+
+    // Multi-line comment
+    if (code[i] === '/' && code[i + 1] === '*') {
+      i += 2;
+      while (i < code.length && !(code[i] === '*' && code[i + 1] === '/')) i++;
+      i += 2;
+      continue;
+    }
+
+    // Template literal
+    if (code[i] === '`') {
+      result += ' ';
+      i++;
+      while (i < code.length) {
+        if (code[i] === '\\') {
+          i += 2;
+          continue;
+        }
+        if (code[i] === '`') {
+          i++;
+          break;
+        }
+        if (code[i] === '$' && code[i + 1] === '{') {
+          i += 2;
+          let depth = 1;
+          while (i < code.length && depth > 0) {
+            if (code[i] === '{') depth++;
+            else if (code[i] === '}') depth--;
+            i++;
+          }
+          continue;
+        }
+        i++;
+      }
+      continue;
+    }
+
+    // String
+    if (code[i] === '"' || code[i] === "'") {
+      const quote = code[i];
+      result += ' ';
+      i++;
+      while (i < code.length) {
+        if (code[i] === '\\') {
+          i += 2;
+          continue;
+        }
+        if (code[i] === quote) {
+          i++;
+          break;
+        }
+        i++;
+      }
+      continue;
+    }
+
+    result += code[i];
+    i++;
+  }
+
+  return result;
+}

package/src/transform/index.js

@@ -0,0 +1,10 @@
+/**
+ * Code Transformations
+ *
+ * Utilities for transforming code for REPL execution.
+ * @module transform
+ */
+
+export { transformForPersistence } from './persistence.js';
+export { wrapForAsync, wrapWithLastExpression } from './async.js';
+export { extractDeclaredVariables } from './extract.js';

package/src/transform/persistence.js

@@ -0,0 +1,176 @@
+/**
+ * Persistence Transform
+ *
+ * Transforms const/let declarations to var for persistence across executions.
+ * In a REPL, we want variables to persist between cells. const/let are
+ * block-scoped and would be lost; var attaches to the global scope.
+ *
+ * @module transform/persistence
+ */
+
+/**
+ * Transform const/let declarations to var for persistence.
+ *
+ * @param {string} code - Source code
+ * @returns {string} Transformed code
+ *
+ * @example
+ * transformForPersistence('const x = 1; let y = 2;')
+ * // Returns: 'var x = 1; var y = 2;'
+ */
+export function transformForPersistence(code) {
+  // Use a state machine approach to avoid transforming inside strings/comments
+  let result = '';
+  let i = 0;
+  const len = code.length;
+
+  while (i < len) {
+    // Check for single-line comment
+    if (code[i] === '/' && code[i + 1] === '/') {
+      const start = i;
+      i += 2;
+      while (i < len && code[i] !== '\n') i++;
+      result += code.slice(start, i);
+      continue;
+    }
+
+    // Check for multi-line comment
+    if (code[i] === '/' && code[i + 1] === '*') {
+      const start = i;
+      i += 2;
+      while (i < len && !(code[i] === '*' && code[i + 1] === '/')) i++;
+      i += 2;
+      result += code.slice(start, i);
+      continue;
+    }
+
+    // Check for template literal
+    if (code[i] === '`') {
+      const start = i;
+      i++;
+      while (i < len) {
+        if (code[i] === '\\') {
+          i += 2;
+          continue;
+        }
+        if (code[i] === '`') {
+          i++;
+          break;
+        }
+        // Handle ${...} - need to track nested braces
+        if (code[i] === '$' && code[i + 1] === '{') {
+          i += 2;
+          let braceDepth = 1;
+          while (i < len && braceDepth > 0) {
+            if (code[i] === '{') braceDepth++;
+            else if (code[i] === '}') braceDepth--;
+            i++;
+          }
+          continue;
+        }
+        i++;
+      }
+      result += code.slice(start, i);
+      continue;
+    }
+
+    // Check for string (single or double quote)
+    if (code[i] === '"' || code[i] === "'") {
+      const quote = code[i];
+      const start = i;
+      i++;
+      while (i < len) {
+        if (code[i] === '\\') {
+          i += 2;
+          continue;
+        }
+        if (code[i] === quote) {
+          i++;
+          break;
+        }
+        i++;
+      }
+      result += code.slice(start, i);
+      continue;
+    }
+
+    // Check for regex (simple heuristic)
+    if (code[i] === '/' && i > 0) {
+      const prev = code[i - 1];
+      // Regex can follow: ( = : [ ! & | ? { } ; , \n
+      if ('(=:[!&|?{};,\n'.includes(prev) || /\s/.test(prev)) {
+        const start = i;
+        i++;
+        while (i < len) {
+          if (code[i] === '\\') {
+            i += 2;
+            continue;
+          }
+          if (code[i] === '/') {
+            i++;
+            // Skip flags
+            while (i < len && /[gimsuy]/.test(code[i])) i++;
+            break;
+          }
+          if (code[i] === '\n') break; // Invalid regex
+          i++;
+        }
+        result += code.slice(start, i);
+        continue;
+      }
+    }
+
+    // Check for const/let keywords
+    if (isWordBoundary(code, i)) {
+      if (code.slice(i, i + 5) === 'const' && isWordBoundary(code, i + 5)) {
+        result += 'var';
+        i += 5;
+        continue;
+      }
+      if (code.slice(i, i + 3) === 'let' && isWordBoundary(code, i + 3)) {
+        result += 'var';
+        i += 3;
+        continue;
+      }
+    }
+
+    result += code[i];
+    i++;
+  }
+
+  return result;
+}
+
+/**
+ * Check if position is at a word boundary
+ * @param {string} code
+ * @param {number} pos
+ * @returns {boolean}
+ */
+function isWordBoundary(code, pos) {
+  if (pos === 0) return true;
+  if (pos >= code.length) return true;
+
+  const before = code[pos - 1];
+  const after = code[pos];
+
+  const isWordChar = (c) => /[a-zA-Z0-9_$]/.test(c);
+
+  // Boundary if previous char is not a word char
+  if (pos > 0 && isWordChar(before)) return false;
+  // Or if position is at end and next char is not word char
+  if (pos < code.length && !isWordChar(after)) return true;
+
+  return true;
+}
+
+/**
+ * Check if position after keyword is a word boundary
+ * @param {string} code
+ * @param {number} pos - Position after the keyword
+ * @returns {boolean}
+ */
+function isWordBoundaryAfter(code, pos) {
+  if (pos >= code.length) return true;
+  return !/[a-zA-Z0-9_$]/.test(code[pos]);
+}

package/src/types/analysis.js

@@ -0,0 +1,24 @@
+/**
+ * Analysis Types
+ *
+ * Types for code analysis (MRP /is_complete and /format endpoints).
+ * @module types/analysis
+ */
+
+/**
+ * @typedef {'complete' | 'incomplete' | 'invalid' | 'unknown'} CompletenessStatus
+ */
+
+/**
+ * @typedef {Object} IsCompleteResult
+ * @property {CompletenessStatus} status - Completeness status
+ * @property {string} [indent] - Suggested indent for continuation
+ */
+
+/**
+ * @typedef {Object} FormatResult
+ * @property {string} formatted - Formatted code
+ * @property {boolean} changed - Whether code was changed
+ */
+
+export {};

package/src/types/capabilities.js

@@ -0,0 +1,44 @@
+/**
+ * Capabilities Types
+ *
+ * Types for runtime capability discovery (MRP /capabilities endpoint).
+ * @module types/capabilities
+ */
+
+/**
+ * @typedef {Object} Capabilities
+ * @property {string} runtime - Runtime identifier
+ * @property {string} version - Runtime version
+ * @property {string[]} languages - Supported language identifiers
+ * @property {Features} features - Feature support flags
+ * @property {string} [lspFallback] - LSP fallback WebSocket URL
+ * @property {string} defaultSession - Default session ID
+ * @property {number} maxSessions - Maximum concurrent sessions
+ * @property {BrowserEnvironment} environment - Environment information
+ */
+
+/**
+ * @typedef {Object} Features
+ * @property {boolean} execute - Execute code and return result
+ * @property {boolean} executeStream - Stream execution output
+ * @property {boolean} interrupt - Interrupt running execution
+ * @property {boolean} complete - Tab completion from live session
+ * @property {boolean} inspect - Get symbol info (signature, docs, source)
+ * @property {boolean} hover - Quick value/type preview
+ * @property {boolean} variables - List variables in namespace
+ * @property {boolean} variableExpand - Drill into objects
+ * @property {boolean} reset - Clear namespace without destroying session
+ * @property {boolean} isComplete - Check if code is complete statement
+ * @property {boolean} format - Format/prettify code
+ * @property {boolean} assets - Asset support (blob URLs)
+ */
+
+/**
+ * @typedef {Object} BrowserEnvironment
+ * @property {string} userAgent - User agent string
+ * @property {string} language - Browser language
+ * @property {string} platform - Platform
+ * @property {boolean} isSecureContext - Is secure context (HTTPS)
+ */
+
+export {};

package/src/types/completion.js

@@ -0,0 +1,47 @@
+/**
+ * Completion Types
+ *
+ * Types for code completion (MRP /complete endpoint).
+ * @module types/completion
+ */
+
+/**
+ * @typedef {'invoked' | 'character' | 'incomplete'} TriggerKind
+ */
+
+/**
+ * @typedef {Object} CompleteOptions
+ * @property {string} [session] - Session ID
+ * @property {TriggerKind} [triggerKind='invoked'] - What triggered completion
+ * @property {string} [triggerCharacter] - Character that triggered
+ */
+
+/**
+ * @typedef {'runtime' | 'lsp' | 'static'} CompletionSource
+ */
+
+/**
+ * @typedef {Object} CompletionResult
+ * @property {CompletionItem[]} matches - Completion items
+ * @property {number} cursorStart - Start of text to replace
+ * @property {number} cursorEnd - End of text to replace
+ * @property {CompletionSource} source - Where completions came from
+ */
+
+/**
+ * @typedef {'variable' | 'function' | 'method' | 'property' | 'class' | 'module' | 'keyword' | 'constant' | 'field' | 'value' | 'snippet'} CompletionKind
+ */
+
+/**
+ * @typedef {Object} CompletionItem
+ * @property {string} label - Display label
+ * @property {string} [insertText] - Text to insert (if different from label)
+ * @property {CompletionKind} kind - Item kind for icon
+ * @property {string} [detail] - Short description
+ * @property {string} [documentation] - Documentation (markdown)
+ * @property {string} [valuePreview] - Live value preview (from runtime)
+ * @property {string} [type] - Type string
+ * @property {number} [sortPriority] - Sort priority (lower = higher)
+ */
+
+export {};