path: root/SPECS/core/shell-parser.js

/**
 * Shell Command Parser and Processor
 *
 * Provides advanced shell command parsing with support for:
 * - Complex shell operators (||, &&, ;;, |&, <(, <<<, >>, >&, <&, etc.)
 * - Quote handling (single and double quotes)
 * - Variable substitution with ${} syntax
 * - Pattern matching and globbing
 * - Safe escaping for command injection protection
 */

class ShellParser {
  constructor() {
    // Shell operators that need special handling
    this.SHELL_OPERATORS = [
      "\\|\\|", // Logical OR
      "\\&\\&", // Logical AND
      ";;", // Command separator
      "\\|\\&", // Pipe with stderr
      "\\<\\(", // Process substitution
      "\\<\\<\\<", // Here string
      ">>", // Append redirect
      ">\\&", // Redirect with file descriptor
      "<\\&", // Input redirect with file descriptor
      "[&;()|<>]", // Basic operators
    ];

    this.operatorPattern = `(?:${this.SHELL_OPERATORS.join("|")})`;
    this.operatorRegex = new RegExp(`^${this.operatorPattern}$`);

    // Characters that need escaping in shell contexts
    this.SHELL_META_CHARS = "|&;()<> \t";

    // Patterns for quoted strings
    this.DOUBLE_QUOTE_PATTERN = '"((\\\\"|[^"])*?)"';
    this.SINGLE_QUOTE_PATTERN = "'((\\\\'|[^'])*?)'";
    this.COMMENT_PATTERN = /^#$/;

    // Quote characters
    this.SINGLE_QUOTE = "'";
    this.DOUBLE_QUOTE = '"';
    this.VARIABLE_PREFIX = "$";

    // Generate unique delimiter for variable substitution
    this.DELIMITER = this.generateUniqueDelimiter();
    this.delimiterRegex = new RegExp(`^${this.DELIMITER}`);
  }

  /**
   * Generate a unique delimiter for variable substitution
   * @returns {string} Unique delimiter string
   */
  generateUniqueDelimiter() {
    let delimiter = "";
    const maxValue = 4294967296; // 2^32

    for (let i = 0; i < 4; i++) {
      delimiter += (maxValue * Math.random()).toString(16);
    }

    return delimiter;
  }

  /**
   * Escape shell command arguments for safe execution
   * @param {Array} args - Array of command arguments
   * @returns {string} Safely escaped command string
   */
  escapeShellCommand(args) {
    return args
      .map((arg) => {
        if (arg === "") return "''";

        // Handle objects with operation property
        if (arg && typeof arg === "object" && arg.op) {
          return arg.op.replace(/(.)/g, "\\$1");
        }

        // Handle strings with spaces but no single quotes
        if (/["\s]/.test(arg) && !/'/.test(arg)) {
          return "'" + arg.replace(/(['\\])/g, "\\$1") + "'";
        }

        // Handle strings with quotes and spaces
        if (/["'\s]/.test(arg)) {
          return '"' + arg.replace(/(["\\$`!])/g, "\\$1") + '"';
        }

        // Escape other shell metacharacters
        return String(arg).replace(
          /([A-Za-z]:)?([#!"$&'()*,:;<=>?@[\\\]^`{|}])/g,
          "$1\\$2",
        );
      })
      .join(" ");
  }

  /**
   * Find all regex matches with proper index handling
   * @param {string} text - Text to search
   * @param {RegExp} regex - Regular expression to match
   * @returns {Array} Array of match results
   */
  findMatches(text, regex) {
    const originalIndex = regex.lastIndex;
    const matches = [];
    let match;

    while ((match = regex.exec(text))) {
      matches.push(match);

      // Prevent infinite loops on zero-width matches
      if (regex.lastIndex === match.index) {
        regex.lastIndex += 1;
      }
    }

    regex.lastIndex = originalIndex;
    return matches;
  }

  /**
   * Substitute variables in shell commands
   * @param {Object|Function} variables - Variable mapping or function
   * @param {string} delimiter - Delimiter prefix
   * @param {string} key - Variable key to substitute
   * @returns {string} Substituted value
   */
  substituteVariable(variables, delimiter, key) {
    const value =
      typeof variables === "function" ? variables(key) : variables[key];

    if (typeof value === "undefined" && key !== "") {
      return "";
    } else if (typeof value === "undefined") {
      return "$";
    }

    if (typeof value === "object") {
      return (
        delimiter + this.DELIMITER + JSON.stringify(value) + this.DELIMITER
      );
    }

    return delimiter + value;
  }

  /**
   * Parse shell command with variable substitution and quote handling
   * @param {string} command - Shell command to parse
   * @param {Object|Function} variables - Variable mapping
   * @param {Object} options - Parsing options
   * @returns {Array} Parsed command tokens
   */
  parseShellCommand(command, variables = {}, options = {}) {
    const escapeChar = options.escape || "\\";

    // Build regex pattern for tokenization
    const tokenPattern = `(\\${escapeChar}['"\${this.SHELL_META_CHARS}]|[^\\s'"${this.SHELL_META_CHARS}])+`;
    const fullPattern = [
      `(${this.operatorPattern})`,
      `(${tokenPattern}|${this.DOUBLE_QUOTE_PATTERN}|${this.SINGLE_QUOTE_PATTERN})+`,
    ].join("|");

    const tokenRegex = new RegExp(fullPattern, "g");
    const matches = this.findMatches(command, tokenRegex);

    if (matches.length === 0) return [];

    let commentFound = false;

    return matches
      .map((match) => {
        const token = match[0];

        if (!token || commentFound) return undefined;

        // Handle shell operators
        if (this.operatorRegex.test(token)) {
          return { op: token };
        }

        let inQuotes = false;
        let escaped = false;
        let result = "";
        let isGlob = false;
        let currentQuote = null;

        const processVariableSubstitution = () => {
          let pos = i + 1;
          let varName, endPos;
          const nextChar = token.charAt(pos);

          if (nextChar === "{") {
            pos++;
            if (token.charAt(pos) === "}") {
              throw new Error(`Bad substitution: ${token.slice(i, pos + 1)}`);
            }

            endPos = token.indexOf("}", pos);
            if (endPos < 0) {
              throw new Error(`Bad substitution: ${token.slice(i)}`);
            }

            varName = token.slice(pos, endPos);
            i = endPos;
          } else if (/[*@#?$!_-]/.test(nextChar)) {
            varName = nextChar;
            i = pos;
          } else {
            const remaining = token.slice(pos);
            const match = remaining.match(/[^\w\d_]/);

            if (!match) {
              varName = remaining;
              i = token.length - 1;
            } else {
              varName = remaining.slice(0, match.index);
              i = pos + match.index - 1;
            }
          }

          return this.substituteVariable(variables, "", varName);
        };

        // Process each character in the token
        for (let i = 0; i < token.length; i++) {
          const char = token.charAt(i);

          // Track glob patterns (* and ?)
          isGlob = isGlob || (!inQuotes && (char === "*" || char === "?"));

          if (escaped) {
            result += char;
            escaped = false;
          } else if (inQuotes) {
            if (char === currentQuote) {
              inQuotes = false;
              currentQuote = null;
            } else if (currentQuote === this.SINGLE_QUOTE) {
              result += char;
            } else if (char === escapeChar) {
              i++;
              const nextChar = token.charAt(i);
              if (
                nextChar === this.DOUBLE_QUOTE ||
                nextChar === escapeChar ||
                nextChar === this.VARIABLE_PREFIX
              ) {
                result += nextChar;
              } else {
                result += escapeChar + nextChar;
              }
            } else if (char === this.VARIABLE_PREFIX) {
              result += processVariableSubstitution();
            } else {
              result += char;
            }
          } else if (char === this.DOUBLE_QUOTE || char === this.SINGLE_QUOTE) {
            inQuotes = true;
            currentQuote = char;
          } else if (this.operatorRegex.test(char)) {
            return { op: token };
          } else if (this.COMMENT_PATTERN.test(char)) {
            commentFound = true;
            const comment = { comment: command.slice(match.index + i + 1) };
            return result.length ? [result, comment] : [comment];
          } else if (char === escapeChar) {
            escaped = true;
          } else if (char === this.VARIABLE_PREFIX) {
            result += processVariableSubstitution();
          } else {
            result += char;
          }
        }

        // Return glob pattern or regular string
        if (isGlob) {
          return { op: "glob", pattern: result };
        }

        return result;
      })
      .reduce((acc, token) => {
        return typeof token === "undefined" ? acc : acc.concat(token);
      }, []);
  }

  /**
   * Main parsing function with post-processing
   * @param {string} command - Shell command string
   * @param {Object|Function} variables - Variable mapping
   * @param {Object} options - Parsing options
   * @returns {Array} Final parsed command tokens
   */
  parse(command, variables, options) {
    const tokens = this.parseShellCommand(command, variables, options);

    if (typeof variables !== "function") {
      return tokens;
    }

    // Post-process tokens for function-based variable substitution
    return tokens.reduce((result, token) => {
      if (typeof token === "object") {
        return result.concat(token);
      }

      const parts = token.split(
        new RegExp(`(${this.DELIMITER}.*?${this.DELIMITER})`, "g"),
      );

      if (parts.length === 1) {
        return result.concat(parts[0]);
      }

      return result.concat(
        parts.filter(Boolean).map((part) => {
          if (this.delimiterRegex.test(part)) {
            return JSON.parse(part.split(this.DELIMITER)[1]);
          }
          return part;
        }),
      );
    }, []);
  }
}

/**
 * Shell command parser utilities
 */
class ShellUtils {
  static quote = new ShellParser().escapeShellCommand.bind(new ShellParser());
  static parse = new ShellParser().parse.bind(new ShellParser());
}

module.exports = {
  ShellParser,
  ShellUtils,
};