From 6cb49b279d3fa7226caf6d10f16341e92768d5c8 Mon Sep 17 00:00:00 2001
From: Gerrit Birkeland <gerrit@gerritbirkeland.com>
Date: Sat, 7 Oct 2023 18:36:33 -0600
Subject: [PATCH] Add sortEntryPoints option

Resolves #2393
---
 CHANGELOG.md                             |  1 +
 src/lib/converter/plugins/GroupPlugin.ts | 12 ++++-
 src/lib/utils/options/declaration.ts     |  1 +
 src/lib/utils/options/sources/typedoc.ts |  6 +++
 src/test/behavior.c2.test.ts             | 61 +++++++++++++++---------
 5 files changed, 58 insertions(+), 23 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 864405692..c1177dce0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,7 @@
 ### Features
 
 -   Added `navigationLeaves` option to remove branches from the navigation tree, #2382.
+-   Added `sortEntryPoints` option (defaults to true) to allow disabling entry point sorting, #2393.
 -   Improved support for multi-word searches, #2400.
 
 ### Bug Fixes
diff --git a/src/lib/converter/plugins/GroupPlugin.ts b/src/lib/converter/plugins/GroupPlugin.ts
index eac9c8a4c..3aac703ec 100644
--- a/src/lib/converter/plugins/GroupPlugin.ts
+++ b/src/lib/converter/plugins/GroupPlugin.ts
@@ -27,6 +27,9 @@ export class GroupPlugin extends ConverterComponent {
     @Option("groupOrder")
     accessor groupOrder!: string[];
 
+    @Option("sortEntryPoints")
+    accessor sortEntryPoints!: boolean;
+
     usedBoosts = new Set<string>();
 
     static WEIGHTS: string[] = [];
@@ -90,7 +93,14 @@ export class GroupPlugin extends ConverterComponent {
             reflection.children.length > 0 &&
             !reflection.groups
         ) {
-            this.sortFunction(reflection.children);
+            if (
+                this.sortEntryPoints ||
+                !reflection.children.some((c) =>
+                    c.kindOf(ReflectionKind.Module),
+                )
+            ) {
+                this.sortFunction(reflection.children);
+            }
             reflection.groups = this.getReflectionGroups(reflection.children);
         }
     }
diff --git a/src/lib/utils/options/declaration.ts b/src/lib/utils/options/declaration.ts
index 6dcf0f90e..6365adf72 100644
--- a/src/lib/utils/options/declaration.ts
+++ b/src/lib/utils/options/declaration.ts
@@ -176,6 +176,7 @@ export interface TypeDocOptionMap {
     categoryOrder: string[];
     groupOrder: string[];
     sort: SortStrategy[];
+    sortEntryPoints: boolean;
     kindSortOrder: ReflectionKind.KindString[];
 
     // Validation
diff --git a/src/lib/utils/options/sources/typedoc.ts b/src/lib/utils/options/sources/typedoc.ts
index 6ea6cb592..a6aaaa92f 100644
--- a/src/lib/utils/options/sources/typedoc.ts
+++ b/src/lib/utils/options/sources/typedoc.ts
@@ -686,6 +686,12 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
             }
         },
     });
+    options.addDeclaration({
+        name: "sortEntryPoints",
+        help: "If set, entry points will be subject to the same sorting rules as other reflections.",
+        type: ParameterType.Boolean,
+        defaultValue: true,
+    });
     options.addDeclaration({
         name: "kindSortOrder",
         help: "Specify the sort order for reflections when 'kind' is specified.",
diff --git a/src/test/behavior.c2.test.ts b/src/test/behavior.c2.test.ts
index af8ec5dca..27ad9c4ec 100644
--- a/src/test/behavior.c2.test.ts
+++ b/src/test/behavior.c2.test.ts
@@ -69,29 +69,30 @@ const base = getConverter2Base();
 const app = getConverter2App();
 const program = getConverter2Program();
 
-function convert(entry: string) {
-    const entryPoint = [
-        join(base, `behavior/${entry}.ts`),
-        join(base, `behavior/${entry}.d.ts`),
-        join(base, `behavior/${entry}.tsx`),
-        join(base, `behavior/${entry}.js`),
-        join(base, "behavior", entry, "index.ts"),
-        join(base, "behavior", entry, "index.js"),
-    ].find(existsSync);
-
-    ok(entryPoint, `No entry point found for ${entry}`);
-    const sourceFile = program.getSourceFile(entryPoint);
-    ok(sourceFile, `No source file found for ${entryPoint}`);
-
-    app.options.setValue("entryPoints", [entryPoint]);
+function convert(...entries: [string, ...string[]]) {
+    const entryPoints = entries.map((entry) => {
+        const entryPoint = [
+            join(base, `behavior/${entry}.ts`),
+            join(base, `behavior/${entry}.d.ts`),
+            join(base, `behavior/${entry}.tsx`),
+            join(base, `behavior/${entry}.js`),
+            join(base, "behavior", entry, "index.ts"),
+            join(base, "behavior", entry, "index.js"),
+        ].find(existsSync);
+
+        ok(entryPoint, `No entry point found for ${entry}`);
+        const sourceFile = program.getSourceFile(entryPoint);
+        ok(sourceFile, `No source file found for ${entryPoint}`);
+
+        return { displayName: entry, program, sourceFile, entryPoint };
+    });
+
+    app.options.setValue(
+        "entryPoints",
+        entryPoints.map((e) => e.entryPoint),
+    );
     clearCommentCache();
-    return app.converter.convert([
-        {
-            displayName: entry,
-            program,
-            sourceFile,
-        },
-    ]);
+    return app.converter.convert(entryPoints);
 }
 
 describe("Behavior Tests", () => {
@@ -953,4 +954,20 @@ describe("Behavior Tests", () => {
             "With Spaces",
         ]);
     });
+
+    it("Supports disabling sorting of entry points #2393", () => {
+        app.options.setValue("sort", ["alphabetical"]);
+        const project = convert("blockComment", "asConstEnum");
+        equal(project.children?.map((c) => c.name), [
+            "asConstEnum",
+            "blockComment",
+        ]);
+
+        app.options.setValue("sortEntryPoints", false);
+        const project2 = convert("blockComment", "asConstEnum");
+        equal(project2.children?.map((c) => c.name), [
+            "blockComment",
+            "asConstEnum",
+        ]);
+    });
 });