Merge pull request #2852 from balena-io/remove-custom-os-command-sorting

Remove custom sorting of OS commands in docs in favor of alphabetizing

automation/capitanodoc/markdown.ts

@@ -18,9 +18,8 @@ import { Parser } from '@oclif/core';
 import * as ent from 'ent';
 import * as _ from 'lodash';
 
-import { getManualSortCompareFunction } from '../../src/utils/helpers';
 import { capitanoizeOclifUsage } from '../../src/utils/oclif-utils';
-import type { Category, Document, OclifCommand } from './doc-types';
+import type { Category, Document } from './doc-types';
 
 function renderOclifCommand(command: Category['commands'][0]): string[] {
 	const result = [`## ${ent.encode(command.name || '')}`];
@@ -98,33 +97,7 @@ function renderToc(categories: Category[]): string[] {
 	return result;
 }
 
-const manualCategorySorting: { [category: string]: string[] } = {
-	'Environment Variables': ['envs', 'env rm', 'env add', 'env rename'],
-	OS: [
-		'os versions',
-		'os download',
-		'os build config',
-		'os configure',
-		'os initialize',
-	],
-};
-
-function sortCommands(doc: Document): void {
-	for (const category of doc.categories) {
-		if (category.title in manualCategorySorting) {
-			category.commands = category.commands.sort(
-				getManualSortCompareFunction<OclifCommand, string>(
-					manualCategorySorting[category.title],
-					(cmd: OclifCommand, x: string) =>
-						(cmd.usage || '').toString().replace(/\W+/g, ' ').includes(x),
-				),
-			);
-		}
-	}
-}
-
 export function render(doc: Document) {
-	sortCommands(doc);
 	const result = [
 		`# ${doc.title}`,
 		doc.introduction,

npm-shrinkwrap.json

@@ -14356,9 +14356,10 @@
       }
     },
     "node_modules/prebuild-install/node_modules/node-abi": {
-      "version": "3.68.0",
+      "version": "3.71.0",
-      "resolved": "https://registry.npmjs.org/node-abi/-/node-abi-3.68.0.tgz",
+      "resolved": "https://registry.npmjs.org/node-abi/-/node-abi-3.71.0.tgz",
-      "integrity": "sha512-7vbj10trelExNjFSBm5kTvZXXa7pZyKWx9RCKIyqe6I9Ev3IzGpQoqBP3a+cOdxY+pWj6VkP28n/2wWysBHD/A==",
+      "integrity": "sha512-SZ40vRiy/+wRTf21hxkkEjPJZpARzUMVcJoQse2EF8qkUWbbO2z7vd5oA/H6bVH6SZQ5STGcu0KRDS7biNRfxw==",
+      "license": "MIT",
       "dependencies": {
         "semver": "^7.3.5"
       },
@@ -16866,9 +16867,10 @@
       }
     },
     "node_modules/tslib": {
-      "version": "2.7.0",
+      "version": "2.8.0",
-      "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.7.0.tgz",
+      "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.0.tgz",
-      "integrity": "sha512-gLXCKdN1/j47AiHiOkJN69hJmcbGTHI0ImLmbYLHykhgeN0jVGola9yVjFgzCUklsZQMW55o+dW7IXv3RCXDzA=="
+      "integrity": "sha512-jWVzBLplnCmoaTr13V9dYbiQ99wvZRd0vNWaDRg+aVYRcjDF3nDksxFDE/+fkXnKhpnUUkmx5pK/v8mCtLVqZA==",
+      "license": "0BSD"
     },
     "node_modules/tunnel": {
       "version": "0.0.6",

src/utils/helpers.ts

@@ -271,53 +271,6 @@ export async function retry<T>({
 	return await func();
 }
 
-/**
- * Return a compare(a, b) function suitable for use as the argument for the
- * sort() method of an array. That function will use the given manuallySortedArray
- * as "sorting guidance":
- *   - If both a and b are found in the manuallySortedArray, the returned
- *     compare(a, b) function will follow that ordering.
- *   - If neither a nor b are found in the manuallySortedArray, the returned
- *     compare(a, b) function will compare a and b using the standard '<' and
- *     '>' Javascript operators.
- *   - If only a or only b are found in the manuallySortedArray, the returned
- *     compare(a, b) function will treat the element that was found as being
- *     "smaller than" the not-found element (i.e. found elements appear before
- *     not-found elements in sorted order).
- *
- * The equalityFunc(a, x) argument is a function used to compare the items
- * being sorted against the items in the manuallySortedArray. For example, if
- * equalityFunc was (a, x) => a.startsWith(x), where a is an item being sorted
- * and x is an item in the manuallySortedArray, then the manuallySortedArray
- * could contain prefix substrings to guide the sorting.
- *
- * @param manuallySortedArray A pre-sorted array to guide the sorting
- * @param equalityFunc An optional function used to compare the items being
- *   sorted against items in manuallySortedArray. It should return true if
- *   the two items compare equal, otherwise false. The arguments are the
- *   same as provided by the standard Javascript array.findIndex() method.
- */
-export function getManualSortCompareFunction<T, U = T>(
-	manuallySortedArray: U[],
-	equalityFunc: (a: T, x: U, index: number, array: U[]) => boolean,
-): (a: T, b: T) => number {
-	return function (a: T, b: T): number {
-		const indexA = manuallySortedArray.findIndex((x, index, array) =>
-			equalityFunc(a, x, index, array),
-		);
-		const indexB = manuallySortedArray.findIndex((x, index, array) =>
-			equalityFunc(b, x, index, array),
-		);
-		if (indexA >= 0 && indexB >= 0) {
-			return indexA - indexB;
-		} else if (indexA < 0 && indexB < 0) {
-			return a < b ? -1 : a > b ? 1 : 0;
-		} else {
-			return indexA < 0 ? 1 : -1;
-		}
-	};
-}
-
 /**
  * Decide whether the current shell (that executed the CLI process) is a Windows
  * 'cmd.exe' shell, including PowerShell, by checking a few environment