It looks like the docs haven't been updated. There are three commands that you can run to update things when a new rule is added (I often forget to do this myself 😆 ):

• pnpm run update-rule-configs
• pnpm run update-rule-lists
• pnpm run update-rule-docs

The current implementation uses default sorts for some decorators based on the order generated by Angular CLI schematics.

I think this is a good idea. If people are using the schematics to create components, then most of the properties will be in the correct order already.

it would require us to keep these defaults updated whenever the schematics change.

Looking at the git blame for the component schematic, other than a recent change to the standalone property, the template hasn't changed in years, so I don't think there's any need to be concerned about the schematic reordering the properties. In any case, if the default order is ever changed (apart from adding new properties that come into existence), then that would be a breaking change, so I don't think the default order would be changed.

The only think I would suggest is including every property in the defaults, rather than only those that are used by the schematic. For example, there is styleUrl, styleUrls and styles. If you enable this rule and are using styles instead of styleUrl, the that property would be moved to the bottom (I think, I'm not quite sure what happens with properties that aren't listed in the options).

Is there a way to use enums that can be reflected effectively in the rule's schema? I wasn't sure what is the right way to go.

AngularClassDecorators is a non-const enum, so in theory you could dynamically build the schema, but it's a bit ugly.

schema: [
      {
        type: 'object',
        properties: Object.fromEntries(
          Object.keys(AngularClassDecorators).map((key) => [
            key,
            {
              type: 'array',
              items: {
                type: 'string',
              },
            },
          ]),
        ),
        additionalProperties: false,
      },
    ],

That produces an options object that looks like this:

interface Options {
  Component?: string[];
  Directive?: string[];
  Injectable?: string[];
  NgModule?: string[];
  Pipe?: string[];
}

So you'd have to exclude Injectable manually. Personally, I don't think it's worth it. What I think might be better is to define the options for each decorator type as an "enum" so that you can only specify known properties. For example:

Component: {
  type: 'array',
  items: {
    type: 'string',
    enum: [
      'changeDetection',
      'viewProviders',
      'moduleId',
      'templateUrl',
      'template',
      'styleUrl',
      'styleUrls',
      'styles',
      'etc...',
    ],
  },
},

The only downside to this is there a higher maintenance burden - any time a new property is added to the decorators, the rule needs to be updated. However, the upside is that by defining the schema like this, and also making the Options type have the same shape, you'll get strongly-typed configurations, which will make it easy for consumers to know what property names they can specify for each type of decorator. That's just my personal opinion though, and @JamesHenry may have other suggestions. 😃

It looks like the docs haven't been updated. There are three commands that you can run to update things when a new rule is added (I often forget to do this myself 😆 ):

• pnpm run update-rule-configs
• pnpm run update-rule-lists
• pnpm run update-rule-docs

Thanks! i only saw the update-rule-docs so far :).

The only think I would suggest is including every property in the defaults, rather than only those that are used by the schematic. For example, there is styleUrl, styleUrls and styles. If you enable this rule and are using styles instead of styleUrl, the that property would be moved to the bottom (I think, I'm not quite sure what happens with properties that aren't listed in the options).

Good catch, makes also sense in my opinion. I took a look at the metadata to see for substitutions - the only one was component (having style, styleUrls, styleUIrl and templateUrl, template). I've added them as well to the default options.

Thank you also for the inputs regarding the config-schema!

...The only downside to this is there a higher maintenance burden - any time a new property is added to the decorators, the rule needs to be updated.

I totaly see that - so I would wait for @JamesHenry s opinion to that matter :).

hey @bschaeublin, thanks for the PR!
very useful rule, will definitely use it in my team once it's merged

@JamesHenry I'm sorry to tag you, as I see that you always got a lot to do, but after hitting the three month mark, I thought I try my luck to get your feedback on this PR (regarding configuration, and general) after I've made some improvements with @reduckted, so that we could complete it :).

Thank you!

I'm really sorry for the delay @bschaeublin. I have to admit it's because I instinctively strongly dislike sorting rules because of how difficult they are to maintain...

You can see some of the history here: #1781

Auto-fixing for sorting rules is where the problems really materialize and I see you have added it here.

The hugely problematic, but important, thing missing from your tests right now is examples of code comments and how they will be handled during auto-fixing.

I got an LLM to assist me with illustrating my point about just how difficult this is on a made up Component:

@Component({
  /* Multi-line comment above changeDetection (only on one line) */
  changeDetection: ChangeDetectionStrategy.OnPush, // Inline comment for changeDetection

  // Single-line comment above viewProviders
  viewProviders: [
    // Inline comment for first provider in viewProviders
    { provide: 'SomeToken', useValue: 'someValue' } /* Multi-line style comment inline after the object */
  ],

  // Comment above moduleId to illustrate its position
  moduleId: module.id, // Inline comment specifying moduleId

  // Single-line comment above templateUrl
  templateUrl: './foo.component.html', /* Inline multi-line comment after templateUrl */

  /* Multi-line comment above template.
     This template contains an embedded HTML comment. */
  template: `<div>
    <!-- HTML comment inside template -->
    Hello World!
  </div>`, // Inline comment after template

  // Comment above styleUrl to mark its location
  styleUrl: './foo.component.css', // Inline comment for styleUrl

  // Comments for styleUrls demonstrating inline and multi-line styles
  styleUrls: [
    './foo.component.less', // Inline comment after first styleUrl
    './foo.component.scss'  /* Inline comment after second styleUrl */
  ],

  // Comment above styles with an inline style example
  styles: [
    `/* Inline CSS comment within styles */ body { color: red; }` // Inline comment after style string
  ],

  // Comment above animations to show detailed inline annotations
  animations: [
    trigger('fade', [
      transition(':enter', [
        style({ opacity: 0 }),
        animate(500, style({ opacity: 1 }))
      ]) // Inline comment closing the transition array
    ]) // Inline comment closing the trigger
  ],

  // Comment above encapsulation
  encapsulation: ViewEncapsulation.Emulated, // Inline comment for encapsulation setting

  /* Multi-line comment above interpolation specifying the markers used */
  interpolation: ['{{', '}}'], // Inline comment for interpolation markers

  // Single-line comment above preserveWhitespaces
  preserveWhitespaces: false, // Inline comment for preserveWhitespaces

  // Single-line comment above standalone flag
  standalone: true, // Inline comment for standalone component

  // Multi-line comment above imports, demonstrating array comments
  imports: [
    CommonModule, // Inline comment for CommonModule import
    FormsModule   /* Inline comment for FormsModule import */
  ],

  // Comment above schemas with inline array entry comment
  schemas: [
    CUSTOM_ELEMENTS_SCHEMA // Inline comment for custom elements schema
  ],

  /* Multi-line comment above override selector to indicate its importance */
  'override selector': 'foo-bar', // Inline comment for override selector

  // Single-line comment above override inputs
  'override inputs': [
    'input1', // Inline comment for first input
    'input2'  /* Inline comment for second input */
  ],

  // Single-line comment above override outputs
  'override outputs': [
    'output1' // Inline comment for override output
  ],

  // Multi-line comment above override providers with inline object comments
  'override providers': [
    {
      // Inline comment inside the provider object for ServiceA
      provide: 'ServiceA',
      useClass: class ServiceAImpl {} // Inline comment after useClass declaration
    }
  ],

  // Single-line comment above override exportAs
  'override exportAs': 'foo', // Inline comment for exportAs

  // Multi-line comment above override queries to demonstrate inline property comments
  'override queries': {
    query1: { read: ElementRef } // Inline comment for query1
  },

  // Single-line comment above override host
  'override host': {
    '[attr.role]': 'button' // Inline comment for host attribute
  },

  // Single-line comment above override jit
  'override jit': true, // Inline comment for jit flag

  // Multi-line comment above override hostDirectives for clarity
  'override hostDirectives': [
    {
      // Inline comment within host directive object
      directive: class DirectiveA {},
      inputs: ['inputDirective'], // Inline comment for host directive input
      outputs: ['outputDirective'] // Inline comment for host directive output
    }
  ]
})
export class FooComponent {
  // Component implementation goes here
}

It's really no fun at all to maintain sorting ESLint rules 🥲

I'll keep an open mind, though, and wait to hear back from you on how you get on auto-fixing the sorting of the above with the comments being moved to the appropriate new locations

Thanks @JamesHenry for your response, I saw (to late) your comment in another PR as well, that you didn't like these kind of rules for these (proabably truly) difficult handling of comments. So if you're still open to this like you mentioned, I'd like to search for a stable and nice solution.

I think the repository eslint-plugin-perfectionist (which kind soley sorting stuff), do consider comments when re-sorting properties. I saw for example that they work with ranges which contains relevant comments (top, inlinebefore and after), ex. see getNodeRange.

I still have to validate that, but if they solved that problem we could do it similar?
Either way I'd be happy to search for a solution.

I don't have strong opinions about how you solve it, but the challenge is there on the above snippet and whether it can be proven to be auto-fixable, the above should be your unit test input where you prove that the comments get moved appropriately. Note, formatting doesn't have to be absolutely perfect before and after, but the comments have to belong to the same exact code as before