[refactor] Simplify and generalize Module links

This changes the way that we link to modules in order to make it more
generic. The main difference here is that we no longer assume that the
project name has any relation to the module itself, instead we always
use the fully-qualified module name as its id, its link, and title.

There are some pros and cons to this approach:

* Pros
  * More inline with JS/modules as a whole - Since we base everything on
  the full module name, we aren't basing it on arbitrary Ember-only
  concepts, like the Addon/App folders, etc. The build system now just
  receives a tree with a module structure, and assumes that it is the
  correct, canonical structure.
  * More self-documenting - users can know at a glance what the import
  path for an item is just by looking at the sidebar
  * Supports documenting multiple addons in a single project - this is
  important for libraries like ember-decorators that are made up of many
  small packages

* Cons
  * Slightly more verbose - the name of the addon is generally included
  in titles, urls, and import paths, which can be redundant in the
  simple case. This could be special-cased in the future, so we at least
  don't include it in the title for the navigation index.
  * Could be problematic with Node/Browser overlap - users could try to
  have two sets of modules with identical import paths for both the
  Browser and Node (e.g. both have an `index.js`). This is problematic
  in general though, and moving forward Ember-CLI seems to be on a path
  to making sure addons don't do this because its confusing.

Other changes:

* Instead of nesting modules under a `/root` url, we're now nesting them
under `/modules`, so we don't imply that it has anything to do with the
structure of the addon. Everything is just a JS module.
* Fixed routing to resolvable items, components with similar names
should now work.

Author: pzuraq

addon/components/api/x-import-path/component.js

@@ -1,11 +1,7 @@
 import Component from '@ember/component';
 import layout from './template';
-import config from 'dummy/config/environment';
-
-const projectName = config['ember-cli-addon-docs'].projectName;
 
 export default Component.extend({
   layout,
-  classNames: ['import-path'],
-  projectName
+  classNames: ['import-path']
 });

addon/components/api/x-import-path/template.hbs

@@ -7,4 +7,4 @@
 {{/if}}
 
 <span class="hljs-keyword">from</span>
-<span class="hljs-string">'{{projectName}}{{item.file}}'</span>;
+<span class="hljs-string">'{{item.file}}'</span>;

addon/components/docs-viewer/x-nav-item/component.js

@@ -11,6 +11,11 @@ export default Component.extend({
 
   didInsertElement() {
     this._super(...arguments);
+    let model = this.get('model');
+
+    if (typeof model === 'string' && model.includes('#')) {
+      return;
+    }
 
     next(() => {
       this.get('docsRoutes.items').addObject(this);

addon/components/docs-viewer/x-nav/template.hbs

@@ -49,9 +49,11 @@
                 {{/each}}
               {{else}}
                 {{#each-in items as |module items|}}
-                  <li class="docs-viewer__module-heading">
-                    {{module}}
-                  </li>
+                  {{subnav.item module
+                    (concat root '.api.item')
+                    (concat 'modules/' module)
+                    class="docs-viewer__module-heading"
+                  }}
 
                   {{#docs-viewer/x-nav-list as |subnav|}}
                     {{#each items as |item|}}

addon/routes/docs/api/item.js

@@ -5,19 +5,24 @@ export default Route.extend({
   model({ path }) {
     let item;
 
-    if (path.match(/^root\//)) {
+    if (path.match(/^modules\//)) {
       // Find by fully qualified id
-      let itemId = path.replace(/^root\//, '');
-      let [moduleId] = itemId.split('~');
+      let itemId = path.replace(/^modules\//, '');
+      let [moduleId] = itemId.split(/~|#/);
 
       let module = this.store.peekRecord('module', moduleId);
 
       item = module.get('components').findBy('id', itemId)
         || module.get('classes').findBy('id', itemId)
         || module;
     } else {
+      // Create a regex that will match modules by either the path, or the
+      // pod-path (/component, /route, etc)
+      let type = path.match(/^(.*)s\//)[1];
+      let pathRegex = new RegExp(`${path}(/${type})?$`);
+
       let modules = this.store.peekAll('module');
-      let matches = modules.filter(m => m.id.match(path));
+      let matches = modules.filter(m => m.id.match(pathRegex));
       let module = matches[0];
 
       assert(`no modules match the path '${path}'`, matches.length > 0);

ember-cli-build.js

@@ -2,6 +2,8 @@
 
 const EmberAddon = require('ember-cli/lib/broccoli/ember-addon');
 const Project = require('ember-cli/lib/models/project');
+const MergeTrees = require('broccoli-merge-trees');
+const Funnel = require('broccoli-funnel');
 
 module.exports = function(defaults) {
   let project = Project.closestSync(process.cwd());
@@ -21,9 +23,12 @@ module.exports = function(defaults) {
     },
     'ember-cli-addon-docs': {
       projects: {
-        sandbox: {
-          tree: 'sandbox'
-        }
+        sandbox: new MergeTrees([
+          new Funnel('sandbox/app', { destDir: 'sandbox' }),
+          new Funnel('sandbox', {
+            include: ['package.json', 'README.md']
+          })
+        ])
       }
     }
   });

index.js

@@ -10,14 +10,6 @@ const EmberApp = require('ember-cli/lib/broccoli/ember-app'); // eslint-disable-
 const Plugin = require('broccoli-plugin');
 const walkSync = require('walk-sync');
 
-const DEFAULT_PROJECTS = {
-  main: {
-    tree: null,
-    include: null,
-    includeTrees: ['addon']
-  }
-}
-
 module.exports = {
   name: 'ember-cli-addon-docs',
 
@@ -95,7 +87,7 @@ module.exports = {
     }
 
     this.addonOptions = Object.assign({}, includer.options['ember-cli-addon-docs']);
-    this.addonOptions.projects = Object.assign({}, DEFAULT_PROJECTS, this.addonOptions.projects);
+    this.addonOptions.projects = Object.assign({}, this.addonOptions.projects);
 
     includer.options.includeFileExtensionInSnippetNames = includer.options.includeFileExtensionInSnippetNames || false;
     includer.options.snippetSearchPaths = includer.options.snippetSearchPaths || ['tests/dummy/app'];
@@ -182,35 +174,10 @@ module.exports = {
     let project = this.project;
     let docsTrees = [];
 
-    for (let projectName in this.addonOptions.projects) {
-      let docProject = this.addonOptions.projects[projectName];
-
-      let addonSourceTree;
-
-      if (docProject.tree) {
-        addonSourceTree = docProject.tree;
-      } else {
-        let include = docProject.include || [];
-        let includeTrees = docProject.includeTrees || [];
-
-        let includeTreePaths = includeTrees.map(t => parentAddon.treePaths[t]);
-        let includeFunnels = [
-          // We need to be very careful to avoid triggering a watch on the addon root here
-          // because of https://github.com/nodejs/node/issues/15683
-          new Funnel(new UnwatchedDir(parentAddon.root), {
-            include: ['package.json', 'README.md']
-          })
-        ];
-
-        for (let path of include.concat(includeTreePaths)) {
-          let fullPath = `${parentAddon.root}/${path}`;
-          if (fs.existsSync(fullPath)) {
-            includeFunnels.push(new Funnel(fullPath, { destDir: path }));
-          }
-        }
+    this.addonOptions.projects.main = this.addonOptions.projects.main || generateDefaultProject(parentAddon);
 
-        addonSourceTree = new MergeTrees(includeFunnels);
-      }
+    for (let projectName in this.addonOptions.projects) {
+      let addonSourceTree = this.addonOptions.projects[projectName];
 
       let pluginRegistry = new PluginRegistry(project);
 
@@ -279,6 +246,33 @@ function findImporter(addon) {
   }
 }
 
+function generateDefaultProject(parentAddon) {
+  let includeFunnels = [
+    // We need to be very careful to avoid triggering a watch on the addon root here
+    // because of https://github.com/nodejs/node/issues/15683
+    new Funnel(new UnwatchedDir(parentAddon.root), {
+      include: ['package.json', 'README.md']
+    })
+  ];
+
+  let addonTreePath = path.join(parentAddon.root, parentAddon.treePaths['addon']);
+  let testSupportPath = path.join(parentAddon.root, parentAddon.treePaths['addon-test-support']);
+
+  if (fs.existsSync(addonTreePath)) {
+    includeFunnels.push(new Funnel(addonTreePath, {
+      destDir: parentAddon.name
+    }));
+  }
+
+  if (fs.existsSync(testSupportPath)) {
+    includeFunnels.push(new Funnel(testSupportPath, {
+      destDir: `${parentAddon.name}/test-support`
+    }));
+  }
+
+  return new MergeTrees(includeFunnels);
+}
+
 class FindDummyAppFiles extends Plugin {
   build() {
     let addonPath = this.inputPaths[0];

lib/broccoli/docs-compiler.js

@@ -72,76 +72,6 @@ function compileDocDescriptions(modules) {
   });
 }
 
-function stripAppAddonDirs(modules) {
-
-  modules.forEach((module) => {
-    module.file = module.file.replace(/^(app|addon)/, '');
-  });
-
-  eachRelationship(modules, (relationship) => {
-    relationship.forEach((item) => {
-      if (item.file) item.file = item.file.replace(/^(app|addon)/, '');
-      if (item.name) item.name = item.name.replace(/^(app|addon)/, '');
-    });
-  });
-}
-
-/**
- * "Hoists" default exports from a given module. This is particularly useful
- * for class files, which generally only export a single default class and
- * would normally look like this:
- *
- * /classes/foo
- *   FooClass
- * /classes/bar
- *   BarClass
- *
- * Instead they become this:
- *
- * /classes
- *   FooClass
- *   BarClass
- *
- * Since these are the only exports of that type and the default, users can
- * generally infer that they can import the class from the file with the same
- * name as the class or component (in many cases this also doesn't matter
- * since the affected classes will be resolved).
- *
- * If a file has named exports they will continue to appear in that module:
- *
- * /classes
- *   FooClass
- * /classes/foo
- *   HelperClass
- *
- * @param {Object} modules
- */
-function hoistDefaults(modules) {
-  for (let m in modules) {
-    let module = modules[m];
-    let parentModulePath = path.dirname(m);
-
-    let value = _.remove(module, { isDefault: true });
-
-    if (value) {
-      modules[parentModulePath] = (modules[parentModulePath] || []).concat(value);
-    }
-  }
-
-  // Remove any modules without exports now that hoisting is done
-  for (let m in modules) {
-    let module = modules[m];
-
-    if (module.length === 0) {
-      delete modules[m];
-    }
-  }
-
-  return modules;
-}
-
-
-
 const RESOLVED_TYPES = [
   'components',
   'helpers',
@@ -177,23 +107,23 @@ function generateResolvedTypeNavigationItems(modules, type) {
 }
 
 function generateModuleNavigationItems(modules, type) {
-  let navItems = modules.reduce((navItems, m) => {
+  return modules.reduce((navItems, m) => {
     let items = m[type].map((item) => {
+      let path = item.id ? item.id : `${m.id}#${item.name}`;
+
       return {
-        path: `root/${item.id || m.id}`,
+        path: `modules/${path}`,
         name: item.name,
         isDefault: item.exportType === 'default'
       };
     });
 
     if (items.length > 0) {
-        navItems[m.file] = _.sortBy(items, ['name']);
+      navItems[m.file] = _.sortBy(items, ['name']);
     }
 
     return navItems;
   }, {});
-
-  return hoistDefaults(navItems);
 }
 
 function generateNavigationIndex(modules, klasses) {
@@ -255,7 +185,6 @@ module.exports = class DocsCompiler extends CachingWriter {
     removeHiddenDocs(modules);
     removeEmptyModules(modules);
     compileDocDescriptions(modules);
-    stripAppAddonDirs(modules);
 
     let project = {
       id: name,

tests/acceptance/sandbox/api/helpers-test.js

@@ -37,7 +37,7 @@ module('Acceptance | API | helpers', function(hooks) {
 
         assert.equal(
           helperItem.importPath,
-          `import { ${helperName} } from 'ember-cli-addon-docs/helpers/${kebabName}';`,
+          `import { ${helperName} } from 'sandbox/helpers/${kebabName}';`,
           'renders the import path correctly'
         );