node/lib/internal/repl/completion.js

'use strict';

const {
  ArrayPrototypeFilter,
  ArrayPrototypeForEach,
  ArrayPrototypeIncludes,
  ArrayPrototypeMap,
  ArrayPrototypePop,
  ArrayPrototypePush,
  ArrayPrototypePushApply,
  ArrayPrototypeShift,
  ArrayPrototypeSlice,
  ArrayPrototypeSome,
  ArrayPrototypeSort,
  ArrayPrototypeUnshift,
  ObjectGetOwnPropertyDescriptor,
  ObjectGetPrototypeOf,
  ObjectKeys,
  ReflectApply,
  RegExpPrototypeExec,
  SafeSet,
  StringPrototypeCharCodeAt,
  StringPrototypeCodePointAt,
  StringPrototypeEndsWith,
  StringPrototypeSlice,
  StringPrototypeStartsWith,
  StringPrototypeToLocaleLowerCase,
  StringPrototypeTrimStart,
} = primordials;

const {
  kContextId,
  getGlobalBuiltins,
  getReplBuiltinLibs,
  fixReplRequire,
} = require('internal/repl/utils');

const { getReplInspector } = require('internal/repl/inspector');

const CJSModule = require('internal/modules/cjs/loader').Module;

const {
  extensionFormatMap,
} = require('internal/modules/esm/get_format');

const path = require('path');
const fs = require('fs');

const {
  constants: {
    ALL_PROPERTIES,
    SKIP_SYMBOLS,
  },
  getOwnNonIndexProperties,
} = internalBinding('util');

const replCommandRE = /^\s*\.(\w*)$/;
const importRE = /\bimport\s*(?:\(\s*|[^'"`]*?\bfrom\s*)?['"`](([\w@./:-]+\/)?(?:[\w@./:-]*))(?![^'"`])$/;
const requireRE = /\brequire\s*\(\s*['"`](([\w@./:-]+\/)?(?:[\w@./:-]*))(?![^'"`])$/;
const fsAutoCompleteRE = /fs(?:\.promises)?\.\s*[a-z][a-zA-Z]+\(\s*["'](.*)/;
const versionedFileNamesRe = /-\d+\.\d+/;
const relativePathRE = /^\.\.?\//;
const completableLastCharRE = /\w|\.|\$/;
const declarationKeywordRE = /(?:^|[^\w$])(?:var|let|const|class|function)\s+$/;

const kCompletionObjectGroup = 'node-repl-completion';

fixReplRequire(module);

const { BuiltinModule } = require('internal/bootstrap/realm');

const nodeSchemeBuiltinLibs = ArrayPrototypeMap(getReplBuiltinLibs(), (lib) => `node:${lib}`);
ArrayPrototypeForEach(
  BuiltinModule.getSchemeOnlyModuleNames(),
  (lib) => ArrayPrototypePush(nodeSchemeBuiltinLibs, `node:${lib}`),
);

async function complete(line, repl) {
  // Ignore leading whitespace; it could change the outcome (e.g. a lone space
  // should still offer the global scope rather than nothing).
  line = StringPrototypeTrimStart(line);

  let match;
  let result;
  if ((match = RegExpPrototypeExec(replCommandRE, line)) !== null) {
    result = completeReplCommand(repl, match);
  } else if ((match = RegExpPrototypeExec(requireRE, line)) !== null) {
    result = completeRequireSpecifier(repl, match);
  } else if ((match = RegExpPrototypeExec(importRE, line)) !== null) {
    result = completeImportSpecifier(repl, match);
  } else if ((match = RegExpPrototypeExec(fsAutoCompleteRE, line)) !== null &&
             repl.allowBlockingCompletions) {
    result = completeFsPath(match);
  } else if (line.length === 0 ||
             RegExpPrototypeExec(completableLastCharRE, line[line.length - 1]) !== null) {
    result = await completeExpression(repl, line);
  } else {
    result = emptyCompletion();
  }

  return finalizeCompletions(result.completionGroups, result.filter, result.completeOn);
}

/**
 * Filters, sorts, de-duplicates and merges the completion groups into the
 * `[completions, completeOn]` tuple readline expects.
 * @returns {[string[], string]} The completions and the string to complete on.
 */
function finalizeCompletions(completionGroups, filter, completeOn) {
  if (completionGroups.length && filter) {
    const lowerCaseFilter = StringPrototypeToLocaleLowerCase(filter);
    const newCompletionGroups = [];
    ArrayPrototypeForEach(completionGroups, (group) => {
      const filteredGroup = ArrayPrototypeFilter(group, (str) =>
        // Filtering is always case-insensitive, following chromium autocomplete
        // behavior.
        StringPrototypeStartsWith(
          StringPrototypeToLocaleLowerCase(str), lowerCaseFilter),
      );
      if (filteredGroup.length) {
        ArrayPrototypePush(newCompletionGroups, filteredGroup);
      }
    });
    completionGroups = newCompletionGroups;
  }

  const completions = [];
  // Unique completions across all groups.
  const uniqueSet = new SafeSet();
  uniqueSet.add('');
  ArrayPrototypeForEach(completionGroups, (group) => {
    ArrayPrototypeSort(group, (a, b) => (b > a ? 1 : -1));
    const setSize = uniqueSet.size;
    ArrayPrototypeForEach(group, (entry) => {
      if (!uniqueSet.has(entry)) {
        ArrayPrototypeUnshift(completions, entry);
        uniqueSet.add(entry);
      }
    });
    // Add a separator between groups.
    if (uniqueSet.size !== setSize) {
      ArrayPrototypeUnshift(completions, '');
    }
  });

  // Remove obsolete group entry, if present.
  if (completions[0] === '') {
    ArrayPrototypeShift(completions);
  }

  return [completions, completeOn];
}

// A result with nothing to complete (also the shape every handler returns).
function emptyCompletion() {
  return { __proto__: null, completionGroups: [], completeOn: undefined, filter: '' };
}

// Completes REPL dot-commands, e.g. `.bre` -> `.break`.
function completeReplCommand(repl, match) {
  const completeOn = match[1];
  return {
    __proto__: null,
    completionGroups: [ObjectKeys(repl.commands)],
    completeOn,
    filter: completeOn,
  };
}

// Completes the specifier inside `require('...')` with the builtin module names
// and, when blocking completions are allowed, on-disk files and directories.
function completeRequireSpecifier(repl, match) {
  return completeModuleSpecifier(repl, match, {
    __proto__: null,
    // `CJSModule._extensions` can be augmented at runtime (e.g. by loaders), so
    // it is read on every completion rather than cached at module load.
    extensions: ObjectKeys(CJSModule._extensions),
    extraIndexes: ['package.json', 'index'],
    getBasePaths() {
      const paths = [];
      ArrayPrototypePushApply(paths, module.paths);
      ArrayPrototypePushApply(paths, CJSModule.globalPaths);
      return paths;
    },
    // `require('foo')` resolves without the extension, and `require('foo/index')`
    // is redundant with `require('foo')`.
    formatFile(subdir, name, extension) {
      const base = StringPrototypeSlice(name, 0, name.length - extension.length);
      if (subdir && base === 'index') {
        return null;
      }
      return `${subdir}${base}`;
    },
    // CommonJS resolution treats any directory holding an index/`package.json`
    // as requirable, not only those under `node_modules`.
    listsDirectoryIndex() {
      return true;
    },
  });
}

// Completes the specifier inside `import('...')` with the builtin module names
// and, when blocking completions are allowed, importable on-disk files and
// directories.
function completeImportSpecifier(repl, match) {
  return completeModuleSpecifier(repl, match, {
    __proto__: null,
    extensions: ObjectKeys(extensionFormatMap),
    extraIndexes: ['package.json'],
    getBasePaths() {
      return ArrayPrototypeSlice(module.paths);
    },
    // `import()` needs the explicit file extension.
    formatFile(subdir, name) {
      return `${subdir}${name}`;
    },
    // Only bare specifiers resolved from `node_modules` honor a directory's
    // index/`package.json`; relative imports must be spelled out in full.
    listsDirectoryIndex(subdir, isInNodeModules) {
      return !subdir && isInNodeModules;
    },
  });
}

// Shared driver for `require('...')` and `import('...')` specifier completion.
// Both offer the builtin module names plus, when blocking completions are
// allowed, the files and directories reachable from a set of base paths; the
// `options` object captures the few places their resolution rules differ.
function completeModuleSpecifier(repl, match, options) {
  const completeOn = match[1];
  const completionGroups = [];

  if (repl.allowBlockingCompletions) {
    const { extensions, getBasePaths, formatFile, listsDirectoryIndex } = options;
    const subdir = match[2] || '';
    // Filenames that mark a directory as loadable without a trailing slash.
    const indexes = ArrayPrototypeMap(extensions, (ext) => `index${ext}`);
    ArrayPrototypePushApply(indexes, options.extraIndexes);

    const group = [];
    let paths = [];
    if (completeOn === '.') {
      ArrayPrototypePush(group, './', '../');
    } else if (completeOn === '..') {
      ArrayPrototypePush(group, '../');
    } else if (RegExpPrototypeExec(relativePathRE, completeOn) !== null) {
      paths = [process.cwd()];
    } else {
      paths = getBasePaths();
    }

    ArrayPrototypeForEach(paths, (dir) => {
      dir = path.resolve(dir, subdir);
      const isInNodeModules = path.basename(dir) === 'node_modules';
      const dirents = gracefulReaddir(dir, { withFileTypes: true }) || [];
      ArrayPrototypeForEach(dirents, (dirent) => {
        const { name } = dirent;
        if (RegExpPrototypeExec(versionedFileNamesRe, name) !== null ||
            name === '.npm') {
          // Exclude versioned names that 'npm' installs.
          return;
        }

        if (!dirent.isDirectory()) {
          const extension = path.extname(name);
          if (ArrayPrototypeIncludes(extensions, extension)) {
            const completion = formatFile(subdir, name, extension);
            if (completion !== null) {
              ArrayPrototypePush(group, completion);
            }
          }
          return;
        }

        ArrayPrototypePush(group, `${subdir}${name}/`);
        if (listsDirectoryIndex(subdir, isInNodeModules) &&
            hasIndexFile(path.resolve(dir, name), indexes)) {
          ArrayPrototypePush(group, `${subdir}${name}`);
        }
      });
    });
    if (group.length) {
      ArrayPrototypePush(completionGroups, group);
    }
  }

  ArrayPrototypePush(completionGroups, getReplBuiltinLibs(), nodeSchemeBuiltinLibs);
  return { __proto__: null, completionGroups, completeOn, filter: completeOn };
}

// Whether `dir` contains any of the `indexes` files, which makes it loadable by
// its bare name (e.g. `require('foo')` resolving to `foo/index.js`).
function hasIndexFile(dir, indexes) {
  return ArrayPrototypeSome(
    gracefulReaddir(dir) || [],
    (subfile) => ArrayPrototypeIncludes(indexes, subfile),
  );
}

// Completes a filesystem path passed to an `fs` function, e.g.
// `fs.readFile('./<Tab>')`.
function completeFsPath(match) {
  let baseName = '';
  let filePath = match[1];
  let fileList = gracefulReaddir(filePath, { withFileTypes: true });

  if (!fileList) {
    baseName = path.basename(filePath);
    filePath = path.dirname(filePath);
    fileList = gracefulReaddir(filePath, { withFileTypes: true }) || [];
  }

  const completions = ArrayPrototypeMap(
    ArrayPrototypeFilter(
      fileList,
      (dirent) => StringPrototypeStartsWith(dirent.name, baseName),
    ),
    (dirent) => dirent.name,
  );

  return {
    __proto__: null,
    completionGroups: [completions],
    completeOn: baseName,
    filter: '',
  };
}

/**
 * Completes a trailing expression: either a member access (`obj.foo`) or a bare
 * identifier against the global/lexical scope (`Strin`).
 * @returns {Promise<{completionGroups: string[][], completeOn: string, filter: string}>}
 */
async function completeExpression(repl, line) {
  const analysis = analyzeCompletion(line);
  if (analysis === null) {
    return emptyCompletion();
  }

  const { receiver, chaining, completeOn } = analysis;
  // Completions are emitted fully qualified (e.g. `console.log`), so filtering
  // happens against the whole text being completed.
  const filter = completeOn;

  const completionGroups = receiver === null ?
    await completeGlobalScope(repl, filter) :
    await completeMemberExpression(
      getReplInspector(repl), receiver, chaining, repl[kContextId]);

  return { __proto__: null, completionGroups, completeOn, filter };
}

/**
 * Lists completion groups for a bare identifier
 * @returns {Promise<string[][]>} The completion groups
 */
async function completeGlobalScope(repl, filter) {
  const completionGroups = [];

  const lexicalNames =
    await getReplInspector(repl).globalLexicalScopeNames(repl[kContextId]);
  ArrayPrototypePush(completionGroups, lexicalNames);

  let contextProto = repl.context;
  while ((contextProto = ObjectGetPrototypeOf(contextProto)) !== null) {
    ArrayPrototypePush(completionGroups, filteredOwnPropertyNames(contextProto));
  }

  const contextOwnNames = filteredOwnPropertyNames(repl.context);
  if (!repl.useGlobal) {
    // When the context is not `global`, builtins are not own properties of it.
    // `getGlobalBuiltins()` is a `SafeSet`, not an Array-like.
    ArrayPrototypePush(contextOwnNames, ...getGlobalBuiltins());
  }
  ArrayPrototypePush(completionGroups, contextOwnNames);

  if (filter !== '') {
    addCommonWords(completionGroups);
  }

  return completionGroups;
}

/**
 * Lists member-completion groups for `receiver` using the inspector.
 * @returns {Promise<string[][]>} The completion groups
 */
async function completeMemberExpression(inspector, receiver, chaining, contextId) {
  const evaluate = (expression, throwOnSideEffect) => {
    const params = {
      __proto__: null,
      expression,
      throwOnSideEffect,
      objectGroup: kCompletionObjectGroup,
      silent: true,
    };
    if (contextId !== undefined) {
      params.contextId = contextId;
    }
    return inspector.post('Runtime.evaluate', params);
  };

  try {
    let response;
    try {
      response = await evaluate(receiver, true);
    } catch {
      return [];
    }
    // A side effect (getter/call/proxy trap) or any error (e.g. a ReferenceError
    // for an undeclared receiver) means there is nothing safe to complete.
    if (response.exceptionDetails) {
      return [];
    }

    let { objectId } = response.result;
    if (objectId === undefined) {
      const { type, subtype } = response.result;
      if (type === 'undefined' || subtype === 'null') {
        // `null`/`undefined` have no properties to offer.
        return [];
      }
      // A primitive: box it so its wrapper and prototype properties (e.g. a
      // string's `length` and the `String.prototype` methods) are reachable.
      // The receiver was just proven side-effect-free, so re-evaluating it as
      // the argument to `Object(...)` is safe.
      let boxed;
      try {
        boxed = await evaluate(`Object(${receiver})`, false);
      } catch {
        return [];
      }
      if (boxed.exceptionDetails) {
        return [];
      }
      objectId = boxed.result.objectId;
    }

    let properties;
    try {
      properties = await inspector.post('Runtime.getProperties', {
        __proto__: null,
        objectId,
        // `false` walks the whole prototype chain in one call; each descriptor's
        // `isOwn` flag still lets us keep own properties in their own group.
        ownProperties: false,
        // Indexed elements are never useful for property-name completion and
        // asking the inspector to materialize them makes large arrays and typed
        // arrays needlessly expensive.
        nonIndexedPropertiesOnly: true,
        generatePreview: false,
      });
    } catch {
      // e.g. a revoked proxy. Nothing safe to complete.
      return [];
    }

    // Own properties form the first ("closest") group; inherited ones follow.
    const prefix = `${receiver}${chaining}`;
    const own = [];
    const inherited = [];
    ArrayPrototypeForEach(properties.result || [], (descriptor) => {
      if (isNotLegacyObjectPrototypeMethod(descriptor.name)) {
        ArrayPrototypePush(
          descriptor.isOwn ? own : inherited, `${prefix}${descriptor.name}`);
      }
    });

    const groups = [];
    if (own.length) {
      ArrayPrototypePush(groups, own);
    }
    if (inherited.length) {
      ArrayPrototypePush(groups, inherited);
    }
    return groups;
  } finally {
    try {
      await inspector.post('Runtime.releaseObjectGroup', {
        __proto__: null,
        objectGroup: kCompletionObjectGroup,
      });
    } catch {
      // Best-effort cleanup; ignore failures.
    }
  }
}

// Determines what kind of completion `line` is requesting using a backward scan
function analyzeCompletion(line) {
  if (line.length === 0) {
    return { __proto__: null, receiver: null, chaining: '', completeOn: '' };
  }

  if (endsInsideStringLiteral(line)) {
    return null;
  }

  const start = scanReceiverStart(line);
  if (start < 0) {
    // The completion point is inside an unterminated string literal.
    return null;
  }
  const target = StringPrototypeSlice(line, start);
  if (target === '') {
    return null;
  }

  let rest = target;
  if (!StringPrototypeEndsWith(target, '.')) {
    // Strip the trailing partial identifier (e.g. the `lo` in `console.lo`).
    let k = target.length;
    while (k > 0 &&
           isScannerIdentifierPart(StringPrototypeCharCodeAt(target, k - 1))) {
      k--;
    }
    rest = StringPrototypeSlice(target, 0, k);
  }

  if (StringPrototypeEndsWith(rest, '?.')) {
    const receiver = StringPrototypeSlice(rest, 0, -2);
    return receiver === '' ?
      null :
      { __proto__: null, receiver, chaining: '?.', completeOn: target };
  }
  if (StringPrototypeEndsWith(rest, '.')) {
    const receiver = StringPrototypeSlice(rest, 0, -1);
    return receiver === '' ?
      null :
      { __proto__: null, receiver, chaining: '.', completeOn: target };
  }
  if (rest !== '') {
    // A receiver with no trailing member operator (e.g. ending in `]`). There is
    // nothing to scope a member completion to, so bail conservatively.
    return null;
  }

  // A bare identifier. Skip it when it is the name being introduced by a
  // declaration (e.g. `let a`), since there is nothing to complete there.
  if (RegExpPrototypeExec(declarationKeywordRE,
                          StringPrototypeSlice(line, 0, start)) !== null) {
    return null;
  }
  return { __proto__: null, receiver: null, chaining: '', completeOn: target };
}

// Determines whether the completion point sits inside the text
// of an unterminated string or template literal.
function endsInsideStringLiteral(code) {
  const stack = [];
  for (let i = 0; i < code.length; i++) {
    const top = stack.length ? stack[stack.length - 1] : '';
    const ch = code[i];
    if (top === "'" || top === '"') {
      // Inside a single/double-quoted string.
      if (ch === '\\') {
        i++; // Skip the escaped character.
      } else if (ch === top) {
        ArrayPrototypePop(stack);
      }
    } else if (top === '`') {
      // Inside the text portion of a template literal.
      if (ch === '\\') {
        i++;
      } else if (ch === '`') {
        ArrayPrototypePop(stack);
      } else if (ch === '$' && code[i + 1] === '{') {
        ArrayPrototypePush(stack, '{'); // Enter a `${ ... }` substitution.
        i++;
      }
    } else if (ch === "'" || ch === '"' || ch === '`') {
      // Code context: a quote opens a new string or template literal.
      ArrayPrototypePush(stack, ch);
    } else if (ch === '{') {
      ArrayPrototypePush(stack, '{');
    } else if (ch === '}' && top === '{') {
      ArrayPrototypePop(stack);
    }
  }
  const top = stack.length ? stack[stack.length - 1] : '';
  return top === "'" || top === '"' || top === '`';
}

// Scans backward from the end of `code` over a trailing member-access
// expression, returning the index where it starts.
function scanReceiverStart(code) {
  let i = code.length;
  while (i > 0) {
    const ch = code[i - 1];
    if (isScannerIdentifierPart(StringPrototypeCharCodeAt(code, i - 1))) {
      i--;
    } else if (ch === '.') {
      i--;
    } else if (ch === '?' && code[i] === '.') {
      // The optional-chaining operator `?.`.
      i--;
    } else if (ch === ')' || ch === ']') {
      const open = matchBracketStart(code, i - 1);
      if (open < 0) {
        break;
      }
      i = open;
    } else if (ch === '"' || ch === "'" || ch === '`') {
      const open = matchStringStart(code, i - 1, ch);
      if (open < 0) {
        // No matching opening quote before this one means the quote opens an
        // unterminated string literal that the completion point sits inside
        // (e.g. `"n`). There is nothing to complete there.
        return -1;
      }
      i = open;
    } else {
      break;
    }
  }
  return i;
}

// Given the index of a closing `)` or `]`, returns the index of the matching
// opener
function matchBracketStart(code, closeIndex) {
  let depth = 0;
  for (let i = closeIndex; i >= 0; i--) {
    const ch = code[i];
    if (ch === '"' || ch === "'" || ch === '`') {
      i = matchStringStart(code, i, ch);
      if (i < 0) {
        return -1;
      }
      continue;
    }
    if (ch === ')' || ch === ']' || ch === '}') {
      depth++;
    } else if (ch === '(' || ch === '[' || ch === '{') {
      if (--depth === 0) {
        return i;
      }
    }
  }
  return -1;
}

// Given the index of a closing quote, returns the index of the matching opening
// quote
function matchStringStart(code, closeIndex, quote) {
  for (let i = closeIndex - 1; i >= 0; i--) {
    if (code[i] !== quote) {
      continue;
    }
    let backslashes = 0;
    for (let k = i - 1; k >= 0 && code[k] === '\\'; k--) {
      backslashes++;
    }
    if (backslashes % 2 === 0) {
      return i;
    }
  }
  return -1;
}

function isScannerIdentifierPart(code) {
  return (code >= 48 && code <= 57) ||  // 0-9
         (code >= 65 && code <= 90) ||  // A-Z
         (code >= 97 && code <= 122) || // a-z
         code === 36 ||                 // $
         code === 95 ||                 // _
         code > 127;                    // non-ASCII
}

function isIdentifier(str) {
  if (str === '') {
    return false;
  }
  const { isIdentifierStart, isIdentifierChar } =
    require('internal/deps/acorn/acorn/dist/acorn');
  const first = StringPrototypeCodePointAt(str, 0);
  if (!isIdentifierStart(first)) {
    return false;
  }
  const firstLen = first > 0xffff ? 2 : 1;
  for (let i = firstLen; i < str.length; i += 1) {
    const cp = StringPrototypeCodePointAt(str, i);
    if (!isIdentifierChar(cp)) {
      return false;
    }
    if (cp > 0xffff) {
      i += 1;
    }
  }
  return true;
}

function isNotLegacyObjectPrototypeMethod(str) {
  return isIdentifier(str) &&
    str !== '__defineGetter__' &&
    str !== '__defineSetter__' &&
    str !== '__lookupGetter__' &&
    str !== '__lookupSetter__';
}

function filteredOwnPropertyNames(obj) {
  if (!obj) return [];
  // `Object.prototype` is the only non-contrived object that fulfills
  // `Object.getPrototypeOf(X) === null &&
  //  Object.getPrototypeOf(Object.getPrototypeOf(X.constructor)) === X`.
  let isObjectPrototype = false;
  if (ObjectGetPrototypeOf(obj) === null) {
    const ctorDescriptor = ObjectGetOwnPropertyDescriptor(obj, 'constructor');
    if (ctorDescriptor?.value) {
      const ctorProto = ObjectGetPrototypeOf(ctorDescriptor.value);
      isObjectPrototype = ctorProto && ObjectGetPrototypeOf(ctorProto) === obj;
    }
  }
  const filter = ALL_PROPERTIES | SKIP_SYMBOLS;
  return ArrayPrototypeFilter(
    getOwnNonIndexProperties(obj, filter),
    isObjectPrototype ? isNotLegacyObjectPrototypeMethod : isIdentifier);
}

function addCommonWords(completionGroups) {
  // Only words which do not yet exist as global property should be added to
  // this list.
  ArrayPrototypePush(completionGroups, [
    'async', 'await', 'break', 'case', 'catch', 'const', 'continue',
    'debugger', 'default', 'delete', 'do', 'else', 'export', 'false',
    'finally', 'for', 'function', 'if', 'import', 'in', 'instanceof', 'let',
    'new', 'null', 'return', 'switch', 'this', 'throw', 'true', 'try',
    'typeof', 'var', 'void', 'while', 'with', 'yield',
  ]);
}

function gracefulReaddir(...args) {
  try {
    return ReflectApply(fs.readdirSync, null, args);
  } catch {
    // Continue regardless of error.
  }
}

module.exports = {
  complete,
};