ExtensionDiscovery documentation is wrong about scanning profile directories

I guess you could blacklist "profiles" and that would probably work, if the blacklist was settable.

Yes, indeed. I didn't mention in my report, but I had already tried on my local machine to change this empty() to isset() in ExtensionDiscovery:

protected function filterByProfileDirectories(array $all_files) {
    if (empty($this->profileDirectories)) {
      return $all_files;
    }

The first test I tried running (the test I was actually working on) failed to even get through installation because it couldn't find the testing profile. It basically broke testing.

So... I looked into this (fairly messy!!!!) code in ExtensionDiscovery some more. I realized that it was tacitly assuming during scan() that if you were looking for profiles, then profileDirectories() must have been set to NULL. This is not necessarily the case -- it is never actually verified. That assumption also means that if you created an ExtensionDiscovery object and scanned for modules, then later scanned for profiles, it would most likely break.

So, I went through and cleaned up the code and documentation, and fixed that assumption. I ran one test locally to verify that this patch doesn't completely break the testing system... let's see what happens in the full test suite.

Well. I looked into the test fails. We have several places in Core where we were doing things like this:

    $listing = new ExtensionDiscovery($this->root);
    $listing->setProfileDirectories([]);

before doing a scan. What this does:
- If you were scanning for profiles, it has no effect, so it would still do what it always did, and return all profiles (see #3076329: ExtensionDiscovery returns testing profiles even when you ask it not to, which is about that buggy behavior).
- If you were scanning for modules, previously this would prevent the automatic filtering to just the active profile, and now it does what I think it should be doing, which is filtering so that no modules in any profile directories are being scanned.

As a side effect, ModuleExtensionList is able to find modules in non-active profiles. Which I think is actually a bug... But some of the test fails are from expecting this behavior. Others are from the TestDiscovery process making that same assumption. So... I think that it is too dangerous at this point to fix the actual bug, and what we should do to "solve" this problem is document the buggy behavior and how to get around it. So, Here's a new patch. I didn't bother with an interdiff because I really had to start over.

This is just a documentation patch, plus changing names of some local and protected variables from "files" to "extensions" where appropriate. And in one case, in a test that was looking into that protected member variable that I changed the name of.

Updating issue summary.

This issue only ended up doing documentation and local variable name changes. I didn't change the code at all. I decided the scope creep was probably OK because there is no code change, just documentation cleanup... updating title

The code is currently perfectly capable of discovering profiles anywhere it can find modules. If you look at ExtensionDiscovery, it looks everywhere for all extensions, and then categorizes them by type after reading the .info.yml file to find out what type they are. This is necessary, because some test modules (for example) are not under tests/modules but just under tests, so you cannot infer the type unless you look at the .info file. Anyway regarding that see #3076329: ExtensionDiscovery returns testing profiles even when you ask it not to, which moved the profiles to a different location.

That was meant to convey that it is a very deep array. At the top level, the array key is the site root directory. Then at the next level, the search directory. And so on.

I'm not sure how that could be worded better, any suggestions?

Hm... Maybe something like this?