Merge pull request #2620 from NullVoxPopuli/nvp/template-lint-extract-rule-template-sort-invocations

NullVoxPopuli · web-flow · commit b2ea10ea3a0a · 2026-03-21T18:42:46.000-04:00
Extract rule: template-sort-invocations
diff --git a/README.md b/README.md
@@ -283,6 +283,7 @@ rules in templates can be disabled with eslint directives with mustache or html
 | [template-self-closing-void-elements](docs/rules/template-self-closing-void-elements.md)                           | require self-closing on void elements                                        |    | 🔧 |    |
 | [template-simple-modifiers](docs/rules/template-simple-modifiers.md)                                               | require simple modifier syntax                                               |    |    |    |
 | [template-simple-unless](docs/rules/template-simple-unless.md)                                                     | require simple conditions in unless blocks                                   |    |    |    |
+| [template-sort-invocations](docs/rules/template-sort-invocations.md)                                               | require sorted attributes and modifiers                                      |    |    |    |
 | [template-splat-attributes-only](docs/rules/template-splat-attributes-only.md)                                     | disallow ...spread other than ...attributes                                  |    |    |    |
 | [template-style-concatenation](docs/rules/template-style-concatenation.md)                                         | disallow string concatenation in inline styles                               |    |    |    |
 
diff --git a/docs/rules/template-sort-invocations.md b/docs/rules/template-sort-invocations.md
@@ -0,0 +1,84 @@
+# ember/template-sort-invocations
+
+<!-- end auto-generated rule header -->
+
+## Why use it?
+
+The rule helps you standardize templates:
+
+- Component invocations
+- Helper invocations
+- Modifier invocations
+
+By sorting things that are order-independent, you can more easily refactor code. In addition, sorting removes style differences, so you can review another person's code more effectively.
+
+> [!TIP]
+>
+> The `--fix` option for this rule doesn't preserve formatting. You can use `prettier`, [`prettier-plugin-ember-hbs-tag`](https://github.com/ijlee2/prettier-plugin-ember-hbs-tag), and [`prettier-plugin-ember-template-tag`](https://github.com/ember-tooling/prettier-plugin-ember-template-tag) to format templates in `*.hbs`, `hbs` tags, and `<template>` tags, respectively.
+
+## Examples
+
+### Components
+
+When invoking a component, list things in the following order:
+
+1. Arguments
+2. Attributes
+3. Modifiers
+4. Splattributes
+
+The order clearly shows how the component is customized more and more. Things are alphabetized within each group.
+
+```hbs
+<Ui::Button
+  @label='Submit form'
+  @type='submit'
+  data-test-button
+  {{on 'click' this.doSomething}}
+  ...attributes
+/>
+```
+
+> [!NOTE]
+>
+> In rare cases, the order of [`...attributes`](https://guides.emberjs.com/release/components/component-arguments-and-html-attributes/#toc_html-attributes) can matter. Similarly, the order can matter when an [ARIA attribute has multiple values](https://github.com/ijlee2/ember-container-query/issues/38#issuecomment-647017665).
+>
+> Disable the rule per instance in either case.
+
+### Helpers
+
+When invoking a helper, list the named arguments in alphabetical order.
+
+```hbs
+{{t
+  'my-component.description'
+  installedOn=this.installationDate
+  packageName='ember-source'
+  packageVersion='6.0.0'
+}}
+```
+
+### Modifiers
+
+Similarly to helpers, list the named arguments in alphabetical order.
+
+## Limitations
+
+It's intended that there are no options for sorting. Alphabetical sort is the simplest for everyone to understand and to apply across different projects. It's also the easiest to maintain.
+
+To better meet your needs, consider creating a plugin for `ember-template-lint`.
+
+## Known issues
+
+1\. If you passed an empty string as an argument's value, it has been replaced with `{{""}}`. Let [`ember-template-lint`](https://github.com/ember-template-lint/ember-template-lint/blob/master/docs/rule/no-unnecessary-curly-strings.md) fix the formatting change.
+
+```diff
+- <MyComponent @description={{""}} />
++ <MyComponent @description="" />
+```
+
+2\. Comments such as `{{! @glint-expect-error }}` may have shifted. Move them to the correct location.
+
+## References
+
+Source code and tests were copied from [`ember-codemod-sort-invocations`](https://github.com/ijlee2/ember-codemod-sort-invocations).
diff --git a/lib/rules/template-sort-invocations.js b/lib/rules/template-sort-invocations.js
@@ -0,0 +1,289 @@
+/* eslint-disable unicorn/consistent-function-scoping, unicorn/prefer-at */
+/** @type {import('eslint').Rule.RuleModule} */
+module.exports = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'require sorted attributes and modifiers',
+      category: 'Best Practices',
+      url: 'https://github.com/ember-cli/eslint-plugin-ember/tree/master/docs/rules/template-sort-invocations.md',
+      templateMode: 'both',
+    },
+    fixable: null,
+    schema: [],
+    messages: {
+      attributeOrder: '`{{attributeName}}` must appear after `{{expectedAfter}}`',
+      modifierOrder: '`{{{{modifierName}}}}` must appear after `{{{{expectedAfter}}}}`',
+      hashPairOrder: '`{{hashPairName}}` must appear after `{{expectedAfter}}`',
+      splattributesOrder: '`...attributes` must appear after modifiers',
+    },
+    originallyFrom: {
+      name: 'ember-template-lint',
+      rule: 'lib/rules/sort-invocations.js',
+      docs: 'docs/rule/sort-invocations.md',
+      tests: 'test/unit/rules/sort-invocations-test.js',
+    },
+  },
+
+  create(context) {
+    function getAttributeName(node) {
+      return node.name;
+    }
+
+    function getAttributePosition(node) {
+      const name = getAttributeName(node);
+
+      if (name.startsWith('@')) {
+        return 1; // Arguments first
+      }
+
+      if (name === '...attributes') {
+        return 3; // Splattributes last
+      }
+
+      return 2; // Regular attributes in the middle
+    }
+
+    function getHashPairName(node) {
+      return node.key;
+    }
+
+    function getModifierName(node) {
+      if (node.path.type !== 'GlimmerPathExpression') {
+        return '';
+      }
+
+      return node.path.original;
+    }
+
+    function compareAttributes(a, b) {
+      const positionA = getAttributePosition(a);
+      const positionB = getAttributePosition(b);
+
+      if (positionA !== positionB) {
+        return positionA - positionB;
+      }
+
+      const nameA = getAttributeName(a);
+      const nameB = getAttributeName(b);
+
+      return nameA.localeCompare(nameB);
+    }
+
+    function compareHashPairs(a, b) {
+      const nameA = getHashPairName(a);
+      const nameB = getHashPairName(b);
+
+      return nameA.localeCompare(nameB);
+    }
+
+    function compareModifiers(a, b) {
+      const nameA = getModifierName(a);
+      const nameB = getModifierName(b);
+
+      if (nameA !== nameB) {
+        return nameA.localeCompare(nameB);
+      }
+
+      // For 'on' modifiers, sort by event name
+      if (nameA === 'on' && a.params && b.params && a.params.length > 0 && b.params.length > 0) {
+        const eventA = a.params[0];
+        const eventB = b.params[0];
+
+        if (eventA.type === 'GlimmerStringLiteral' && eventB.type === 'GlimmerStringLiteral') {
+          return eventA.value.localeCompare(eventB.value);
+        }
+      }
+
+      return 0;
+    }
+
+    function getUnsortedAttributeIndex(attributes) {
+      return attributes.findIndex((attribute, index) => {
+        if (index === attributes.length - 1) {
+          return false;
+        }
+
+        return compareAttributes(attribute, attributes[index + 1]) > 0;
+      });
+    }
+
+    function getUnsortedHashPairIndex(pairs) {
+      return pairs.findIndex((hashPair, index) => {
+        if (index === pairs.length - 1) {
+          return false;
+        }
+
+        return compareHashPairs(hashPair, pairs[index + 1]) > 0;
+      });
+    }
+
+    function getUnsortedModifierIndex(modifiers) {
+      return modifiers.findIndex((modifier, index) => {
+        if (index === modifiers.length - 1) {
+          return false;
+        }
+
+        return compareModifiers(modifier, modifiers[index + 1]) > 0;
+      });
+    }
+
+    function canSkipSplattributesLast(node) {
+      const { attributes, modifiers } = node;
+
+      if (!attributes || attributes.length === 0 || !modifiers || modifiers.length === 0) {
+        return true;
+      }
+
+      const splattributes = attributes.at(-1);
+      const lastModifier = modifiers.at(-1);
+
+      if (!splattributes || splattributes.name !== '...attributes' || !lastModifier) {
+        return true;
+      }
+
+      // Check that ...attributes appears after the last modifier
+      const splattributesPosition = splattributes.loc.start;
+      const lastModifierPosition = lastModifier.loc.start;
+
+      if (splattributesPosition.line > lastModifierPosition.line) {
+        return true;
+      }
+
+      return (
+        splattributesPosition.line === lastModifierPosition.line &&
+        splattributesPosition.column > lastModifierPosition.column
+      );
+    }
+
+    return {
+      GlimmerElementNode(node) {
+        const { attributes, modifiers } = node;
+
+        if (attributes && attributes.length > 1) {
+          const index = getUnsortedAttributeIndex(attributes);
+
+          if (index !== -1) {
+            context.report({
+              node: attributes[index],
+              messageId: 'attributeOrder',
+              data: {
+                attributeName: getAttributeName(attributes[index]),
+                expectedAfter: getAttributeName(attributes[index + 1]),
+              },
+            });
+          }
+        }
+
+        if (modifiers && modifiers.length > 1) {
+          const index = getUnsortedModifierIndex(modifiers);
+
+          if (index !== -1) {
+            context.report({
+              node: modifiers[index],
+              messageId: 'modifierOrder',
+              data: {
+                modifierName: getModifierName(modifiers[index]),
+                expectedAfter: getModifierName(modifiers[index + 1]),
+              },
+            });
+          }
+        }
+
+        if (!canSkipSplattributesLast(node)) {
+          const splattributes = attributes.at(-1);
+
+          // When ...attributes is the only attribute, report as attributeOrder
+          // (the ordering issue is that ...attributes should appear after modifiers)
+          if (attributes.length === 1) {
+            context.report({
+              node: splattributes,
+              messageId: 'attributeOrder',
+              data: {
+                attributeName: '...attributes',
+                expectedAfter: 'modifiers',
+              },
+            });
+          } else {
+            context.report({
+              node: splattributes,
+              messageId: 'splattributesOrder',
+            });
+          }
+        }
+      },
+
+      GlimmerBlockStatement(node) {
+        if (node.hash && node.hash.pairs && node.hash.pairs.length > 1) {
+          const index = getUnsortedHashPairIndex(node.hash.pairs);
+
+          if (index !== -1) {
+            context.report({
+              node: node.hash.pairs[index],
+              messageId: 'hashPairOrder',
+              data: {
+                hashPairName: getHashPairName(node.hash.pairs[index]),
+                expectedAfter: getHashPairName(node.hash.pairs[index + 1]),
+              },
+            });
+          }
+        }
+      },
+
+      GlimmerMustacheStatement(node) {
+        if (node.hash && node.hash.pairs && node.hash.pairs.length > 1) {
+          const index = getUnsortedHashPairIndex(node.hash.pairs);
+
+          if (index !== -1) {
+            // Component invocations with a string positional param (e.g. {{component "ui/button" ...}})
+            // treat hash pairs as component attributes
+            const isComponentInvocation =
+              node.path &&
+              node.path.original === 'component' &&
+              node.params &&
+              node.params.length > 0 &&
+              node.params[0].type === 'GlimmerStringLiteral';
+
+            if (isComponentInvocation) {
+              context.report({
+                node: node.hash.pairs[index],
+                messageId: 'attributeOrder',
+                data: {
+                  attributeName: getHashPairName(node.hash.pairs[index]),
+                  expectedAfter: getHashPairName(node.hash.pairs[index + 1]),
+                },
+              });
+            } else {
+              context.report({
+                node: node.hash.pairs[index],
+                messageId: 'hashPairOrder',
+                data: {
+                  hashPairName: getHashPairName(node.hash.pairs[index]),
+                  expectedAfter: getHashPairName(node.hash.pairs[index + 1]),
+                },
+              });
+            }
+          }
+        }
+      },
+
+      GlimmerSubExpression(node) {
+        if (node.hash && node.hash.pairs && node.hash.pairs.length > 1) {
+          const index = getUnsortedHashPairIndex(node.hash.pairs);
+
+          if (index !== -1) {
+            context.report({
+              node: node.hash.pairs[index],
+              messageId: 'hashPairOrder',
+              data: {
+                hashPairName: getHashPairName(node.hash.pairs[index]),
+                expectedAfter: getHashPairName(node.hash.pairs[index + 1]),
+              },
+            });
+          }
+        }
+      },
+    };
+  },
+};
+/* eslint-enable unicorn/consistent-function-scoping, unicorn/prefer-at */
diff --git a/tests/lib/rules/template-sort-invocations.js b/tests/lib/rules/template-sort-invocations.js
