Function validatePathWithinRoot

src/utils.ts:110–146

(
  projectRoot: string,
  filePath: string,
  options?: { allowSymlinkEscape?: boolean }
)

 *   escapes the root
 */
export function validatePathWithinRoot(
  projectRoot: string,
  filePath: string,
  options?: { allowSymlinkEscape?: boolean }
): string | null {
  const resolved = path.resolve(projectRoot, filePath);
  const normalizedRoot = path.resolve(projectRoot);

  // 1. Lexical containment — cheap, catches `../` traversal. Applies even on
  //    the indexing read path: a crafted `../` escape is still rejected.
  if (!isWithinDir(resolved, normalizedRoot)) {
    return null;
  }

  // 2. Symlink-aware containment — resolve symlinks on both sides and re-check,
  //    so an in-repo symlink whose real target escapes the root is rejected.
  //    The indexing read path (allowSymlinkEscape) skips only this rejection so
  //    it stays consistent with the directory walk, which already followed the
  //    in-root symlink to enumerate these files (#935).
  try {
    const realRoot = fs.realpathSync(normalizedRoot);
    const realResolved = fs.realpathSync(resolved);
    if (options?.allowSymlinkEscape) {
      return realResolved;
    }
    return isWithinDir(realResolved, realRoot) ? realResolved : null;
  } catch (err) {
    // ENOENT: the path doesn't exist yet (a file about to be written, or an
    // index entry for a since-deleted file) — no symlink to follow, and the
    // lexical check already passed, so allow the lexical path. Any other
    // resolution failure (ELOOP, EACCES, …) is treated as unsafe → reject.
    if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
      return resolved;
    }
    return null;
  }
}

/**
 * Validate that a path is a safe project root directory.