Category improvements (TypeStrong#938)

* Improve categories to work at the group level or the container level, add category options for flexibility, add test for categories

* Make some changes for serialization and remove some unused code

Author: jonchardy

src/lib/converter/plugins/CategoryPlugin.ts

@@ -1,10 +1,11 @@
-import { Reflection, ContainerReflection } from '../../models/reflections/index';
+import { Reflection, ContainerReflection, DeclarationReflection } from '../../models';
 import { ReflectionCategory } from '../../models/ReflectionCategory';
-import { SourceDirectory } from '../../models/sources/directory';
 import { Component, ConverterComponent } from '../components';
 import { Converter } from '../converter';
 import { Context } from '../context';
-import { GroupPlugin } from './GroupPlugin';
+import { Option } from '../../utils/component';
+import { ParameterType } from '../../utils/options/declaration';
+import { Comment } from '../../models/comments/index';
 
 /**
  * A handler that sorts and categorizes the found reflections in the resolving phase.
@@ -13,19 +14,57 @@ import { GroupPlugin } from './GroupPlugin';
  */
 @Component({name: 'category'})
 export class CategoryPlugin extends ConverterComponent {
-    /**
-     * Define the sort order of categories. By default, sort alphabetically.
-     */
+    @Option({
+        name: 'defaultCategory',
+        help: 'Specifies the default category for reflections without a category.',
+        type: ParameterType.String,
+        defaultValue: 'Other'
+    })
+    defaultCategory!: string;
+
+    @Option({
+        name: 'categoryOrder',
+        help: 'Specifies the order in which categories appear. * indicates the relative order for categories not in the list.',
+        type: ParameterType.Array
+    })
+    categoryOrder!: string[];
+
+    @Option({
+        name: 'categorizeByGroup',
+        help: 'Specifies whether categorization will be done at the group level.',
+        type: ParameterType.Boolean,
+        defaultValue: true
+    })
+    categorizeByGroup!: boolean;
+
+    // For use in static methods
+    static defaultCategory = 'Other';
     static WEIGHTS: string[] = [];
 
     /**
      * Create a new CategoryPlugin instance.
      */
     initialize() {
         this.listenTo(this.owner, {
+            [Converter.EVENT_BEGIN]:       this.onBegin,
             [Converter.EVENT_RESOLVE]:     this.onResolve,
             [Converter.EVENT_RESOLVE_END]: this.onEndResolve
-        });
+        }, undefined, -200);
+    }
+
+    /**
+     * Triggered when the converter begins converting a project.
+     *
+     * @param context  The context object describing the current state the converter is in.
+     */
+    private onBegin(context: Context) {
+        // Set up static properties
+        if (this.defaultCategory) {
+            CategoryPlugin.defaultCategory = this.defaultCategory;
+        }
+        if (this.categoryOrder) {
+            CategoryPlugin.WEIGHTS = this.categoryOrder;
+        }
     }
 
     /**
@@ -36,13 +75,7 @@ export class CategoryPlugin extends ConverterComponent {
      */
     private onResolve(context: Context, reflection: Reflection) {
         if (reflection instanceof ContainerReflection) {
-            if (reflection.children && reflection.children.length > 0) {
-                reflection.children.sort(GroupPlugin.sortCallback);
-                reflection.categories = CategoryPlugin.getReflectionCategories(reflection.children);
-            }
-            if (reflection.categories && reflection.categories.length > 1) {
-                reflection.categories.sort(CategoryPlugin.sortCatCallback);
-            }
+            this.categorize(reflection);
         }
     }
 
@@ -52,32 +85,44 @@ export class CategoryPlugin extends ConverterComponent {
      * @param context  The context object describing the current state the converter is in.
      */
     private onEndResolve(context: Context) {
-        function walkDirectory(directory: SourceDirectory) {
-            directory.categories = CategoryPlugin.getReflectionCategories(directory.getAllReflections());
+        const project = context.project;
+        this.categorize(project);
+    }
 
-            for (let key in directory.directories) {
-                if (!directory.directories.hasOwnProperty(key)) {
-                    continue;
-                }
-                walkDirectory(directory.directories[key]);
-            }
+    private categorize(obj: ContainerReflection) {
+        if (this.categorizeByGroup) {
+            this.groupCategorize(obj);
+        } else {
+            this.lumpCategorize(obj);
         }
+    }
 
-        const project = context.project;
-        if (project.children && project.children.length > 0) {
-            project.children.sort(GroupPlugin.sortCallback);
-            project.categories = CategoryPlugin.getReflectionCategories(project.children);
-        }
-        if (project.categories && project.categories.length > 1) {
-            project.categories.sort(CategoryPlugin.sortCatCallback);
+    private groupCategorize(obj: ContainerReflection) {
+        if (!obj.groups || obj.groups.length === 0) {
+            return;
         }
-
-        walkDirectory(project.directory);
-        project.files.forEach((file) => {
-            file.categories = CategoryPlugin.getReflectionCategories(file.reflections);
+        obj.groups.forEach((group) => {
+            group.categories = CategoryPlugin.getReflectionCategories(group.children);
+            if (group.categories && group.categories.length > 1) {
+                group.categories.sort(CategoryPlugin.sortCatCallback);
+            } else if (group.categories.length === 1 && group.categories[0].title === CategoryPlugin.defaultCategory) {
+                // no categories if everything is uncategorized
+                group.categories = undefined;
+            }
         });
     }
 
+    private lumpCategorize(obj: ContainerReflection) {
+        if (obj instanceof ContainerReflection) {
+            if (obj.children && obj.children.length > 0) {
+                obj.categories = CategoryPlugin.getReflectionCategories(obj.children);
+            }
+            if (obj.categories && obj.categories.length > 1) {
+                obj.categories.sort(CategoryPlugin.sortCatCallback);
+            }
+        }
+    }
+
     /**
      * Create a categorized representation of the given list of reflections.
      *
@@ -86,23 +131,26 @@ export class CategoryPlugin extends ConverterComponent {
      */
     static getReflectionCategories(reflections: Reflection[]): ReflectionCategory[] {
         const categories: ReflectionCategory[] = [];
+        let defaultCat: ReflectionCategory | undefined;
         reflections.forEach((child) => {
             const childCat = CategoryPlugin.getCategory(child);
             if (childCat === '') {
-              return;
-            }
-            for (let i = 0; i < categories.length; i++) {
-                const category = categories[i];
-
-                if (category.title !== childCat) {
-                    continue;
+                if (!defaultCat) {
+                    defaultCat = categories.find(category => category.title === CategoryPlugin.defaultCategory);
+                    if (!defaultCat) {
+                        defaultCat = new ReflectionCategory(CategoryPlugin.defaultCategory);
+                        categories.push(defaultCat);
+                    }
                 }
-
+                defaultCat.children.push(child);
+                return;
+            }
+            let category = categories.find(cat => cat.title === childCat);
+            if (category) {
                 category.children.push(child);
                 return;
             }
-
-            const category = new ReflectionCategory(childCat);
+            category = new ReflectionCategory(childCat);
             category.children.push(child);
             categories.push(category);
         });
@@ -116,29 +164,31 @@ export class CategoryPlugin extends ConverterComponent {
      * @returns The category the reflection belongs to
      */
     static getCategory(reflection: Reflection): string {
-        if (reflection.comment) {
-            const tags = reflection.comment.tags;
+        function extractCategoryTag(comment: Comment) {
+            const tags = comment.tags;
             if (tags) {
                 for (let i = 0; i < tags.length; i++) {
                     if (tags[i].tagName === 'category') {
                         let tag = tags[i].text;
-                        return (tag.charAt(0).toUpperCase() + tag.slice(1).toLowerCase()).trim();
+                        return tag.trim();
                     }
                 }
             }
+            return '';
         }
-        return '';
-    }
 
-    /**
-     * Callback used to sort reflections by name.
-     *
-     * @param a The left reflection to sort.
-     * @param b The right reflection to sort.
-     * @returns The sorting weight.
-     */
-    static sortCallback(a: Reflection, b: Reflection): number {
-        return a.name > b.name ? 1 : -1;
+        let category = '';
+        if (reflection.comment) {
+            category = extractCategoryTag(reflection.comment);
+        } else if (reflection instanceof DeclarationReflection && reflection.signatures) {
+            // If a reflection has signatures, use the first category tag amongst them
+            reflection.signatures.forEach(sig => {
+                if (sig.comment && category === '') {
+                    category = extractCategoryTag(sig.comment);
+                }
+            });
+        }
+        return category;
     }
 
     /**
@@ -149,16 +199,16 @@ export class CategoryPlugin extends ConverterComponent {
      * @returns The sorting weight.
      */
     static sortCatCallback(a: ReflectionCategory, b: ReflectionCategory): number {
-        const aWeight = CategoryPlugin.WEIGHTS.indexOf(a.title);
-        const bWeight = CategoryPlugin.WEIGHTS.indexOf(b.title);
-        if (aWeight < 0 && bWeight < 0) {
-            return a.title > b.title ? 1 : -1;
-        }
-        if (aWeight < 0) {
-            return 1;
+        let aWeight = CategoryPlugin.WEIGHTS.indexOf(a.title);
+        let bWeight = CategoryPlugin.WEIGHTS.indexOf(b.title);
+        if (aWeight === -1 || bWeight === -1) {
+            let asteriskIndex = CategoryPlugin.WEIGHTS.indexOf('*');
+            if (asteriskIndex === -1) { asteriskIndex = CategoryPlugin.WEIGHTS.length; }
+            if (aWeight === -1) { aWeight = asteriskIndex; }
+            if (bWeight === -1) { bWeight = asteriskIndex; }
         }
-        if (bWeight < 0) {
-            return -1;
+        if (aWeight === bWeight) {
+            return a.title > b.title ? 1 : -1;
         }
         return aWeight - bWeight;
     }

src/lib/models/ReflectionGroup.ts

@@ -1,4 +1,5 @@
 import { Reflection, ReflectionKind } from './reflections/abstract';
+import { ReflectionCategory } from './ReflectionCategory';
 
 /**
  * A group of reflections. All reflections in a group are of the same kind.
@@ -62,6 +63,11 @@ export class ReflectionGroup {
      */
     someChildrenAreExported?: boolean;
 
+    /**
+     * Categories contained within this group.
+     */
+    categories?: ReflectionCategory[];
+
     /**
      * Create a new ReflectionGroup instance.
      *
@@ -106,6 +112,15 @@ export class ReflectionGroup {
             result['children'] = children;
         }
 
+        if (this.categories) {
+            const categories: any[] = [];
+            this.categories.forEach((category) => {
+                categories.push(category.toObject());
+            });
+
+            result['categories'] = categories;
+        }
+
         return result;
     }
 }

src/lib/models/reflections/project.ts

@@ -1,7 +1,6 @@
 import { SourceFile, SourceDirectory } from '../sources/index';
 import { Reflection, ReflectionKind } from './abstract';
 import { ContainerReflection } from './container';
-import { ReflectionCategory } from '../ReflectionCategory';
 
 /**
  * A reflection that represents the root of the project.
@@ -27,11 +26,6 @@ export class ProjectReflection extends ContainerReflection {
      */
     files: SourceFile[] = [];
 
-    /**
-     * All reflections categorized.
-     */
-    categories?: ReflectionCategory[];
-
     /**
      * The name of the project.
      *
@@ -123,25 +117,4 @@ export class ProjectReflection extends ContainerReflection {
 
         return undefined;
     }
-
-    /**
-     * Return a raw object representation of this reflection.
-     * @deprecated Use serializers instead
-     */
-    toObject(): any {
-        const result = super.toObject();
-
-        if (this.categories) {
-            const categories: any[] = [];
-            this.categories.forEach((category) => {
-                categories.push(category.toObject());
-            });
-
-            if (categories.length > 0) {
-                result['categories'] = categories;
-            }
-        }
-
-        return result;
-    }
 }

src/lib/models/sources/directory.ts

@@ -1,5 +1,4 @@
 import { Reflection } from '../reflections/abstract';
-import { ReflectionCategory } from '../ReflectionCategory';
 import { ReflectionGroup } from '../ReflectionGroup';
 import { SourceFile } from './file';
 
@@ -23,8 +22,6 @@ export class SourceDirectory {
 
     groups?: ReflectionGroup[];
 
-    categories?: ReflectionCategory[];
-
     /**
      * A list of all files in this directory.
      */

src/lib/models/sources/file.ts

@@ -1,7 +1,6 @@
 import * as Path from 'path';
 
 import { Reflection } from '../reflections/abstract';
-import { ReflectionCategory } from '../ReflectionCategory';
 import { ReflectionGroup } from '../ReflectionGroup';
 import { SourceDirectory } from './directory';
 
@@ -81,11 +80,6 @@ export class SourceFile {
      */
     groups?: ReflectionGroup[];
 
-    /**
-     * A categorized list of the reflections declared in this file.
-     */
-    categories?: ReflectionCategory[];
-
     /**
      * Create a new SourceFile instance.
      *