fix(core): sort --help output by flag priority (#14869)

(cherry picked from commit 20b66fc)

packages/nx/src/utils/print-help.spec.ts

@@ -0,0 +1,65 @@
+import { Schema } from './params';
+import { logger } from './logger';
+import { printHelp } from './print-help';
+
+describe('printHelp', () => {
+  it('should sort options by priority and name', () => {
+    const schema: Schema = {
+      properties: {
+        aImp: {
+          'x-priority': 'important',
+        },
+        bImp: {
+          'x-priority': 'important',
+        },
+        aNormal: {},
+        bNormal: {},
+        aDep: {
+          'x-deprecated': 'great reason',
+        },
+        bDep: {
+          'x-deprecated': 'even better reason',
+        },
+        aReq: {},
+        bReq: {},
+        aInt: {
+          'x-priority': 'internal',
+        },
+        bInt: {
+          'x-priority': 'internal',
+        },
+      },
+      required: ['aReq', 'bReq'],
+      description: 'description',
+    };
+
+    let output = '';
+    jest.spyOn(logger, 'info').mockImplementation((x) => (output = x));
+
+    printHelp('nx g @nrwl/demo:example', schema, {
+      mode: 'generate',
+      plugin: '@nrwl/demo',
+      entity: 'example',
+      aliases: ['ex'],
+    });
+
+    const flagsFromOutput = output
+      .match(/--[a|b]\S*/g)
+      .map((x) => x.replace('--', ''));
+
+    expect(flagsFromOutput).toMatchInlineSnapshot(`
+      Array [
+        "aReq",
+        "bReq",
+        "aImp",
+        "bImp",
+        "aNormal",
+        "bNormal",
+        "aInt",
+        "bInt",
+        "aDep",
+        "bDep",
+      ]
+    `);
+  });
+});

packages/nx/src/utils/print-help.ts

@@ -214,8 +214,10 @@ function generateOptionsOutput(schema: Schema): string {
     }
   >();
   let requiredSpaceToRenderAllFlagsAndAliases = 0;
-
-  for (const [optionName, optionConfig] of Object.entries(schema.properties)) {
+  const sorted = Object.entries(schema.properties).sort((a, b) =>
+    compareByPriority(a, b, schema)
+  );
+  for (const [optionName, optionConfig] of sorted) {
     const renderedFlagAndAlias =
       `--${optionName}` +
       (optionConfig.alias ? `, -${optionConfig.alias}` : '');
@@ -336,3 +338,44 @@ function generateLinkOutput({
     'Find more information and examples at:'
   )} ${chalk.bold(link)}`;
 }
+
+/**
+ * sorts properties in the following order
+ * - required
+ * - x-priority: important
+ * - everything else
+ * - x-priority: internal
+ * - deprecated
+ * if two properties have equal priority, they are sorted by name
+ */
+function compareByPriority(
+  a: [string, Schema['properties'][0]],
+  b: [string, Schema['properties'][0]],
+  schema: Schema
+): number {
+  function getPriority([name, property]: [
+    string,
+    Schema['properties'][0]
+  ]): number {
+    if (schema.required?.includes(name)) {
+      return 0;
+    }
+    if (property['x-priority'] === 'important') {
+      return 1;
+    }
+    if (property['x-deprecated']) {
+      return 4;
+    }
+    if (property['x-priority'] === 'internal') {
+      return 3;
+    }
+    return 2;
+  }
+
+  const aPriority = getPriority(a);
+  const bPriority = getPriority(b);
+  if (aPriority === bPriority) {
+    return a[0].localeCompare(b[0]);
+  }
+  return aPriority - bPriority;
+}