Skip to main content

sort-top-comments

Enforce alphabetical sorting of top-of-file comments.

Targeted pattern scope​

This rule inspects comments located before the first top-level program node.

Only that top-of-file comment region is considered.

What this rule reports​

If there are at least two top-of-file comments, this rule reports when their order is not alphabetical.

An autofix rewrites that comment span in sorted order.

Why this rule exists​

Sorted file headers reduce churn in shared banner/comment blocks and make them easier to scan.

❌ Incorrect​

// zeta
// alpha
const value = 1;

✅ Correct​

// alpha
// zeta
const value = 1;

Behavior and migration notes​

This rule is autofixable.

The fixer only rewrites the contiguous top comment span before the first statement.

Options​

This rule has no options.

Additional examples​

/* zeta */
/* alpha */
import { run } from "./run";
// ❌ reported and reordered

ESLint flat config example​

import etcMisc from "eslint-plugin-etc-misc";

export default [
 {
  plugins: { "etc-misc": etcMisc },
  rules: {
   "etc-misc/sort-top-comments": "error",
  },
 },
];

When not to use it​

Disable this rule if top comments intentionally represent ordered execution steps, chronological logs, or legal blocks with fixed sequence.

Package documentation​

Rule catalog ID: R097

Further reading​

Adoption resources​

  • Start at warning level in CI, then move to error after cleanup.
  • Use focused codemods/autofix batches per package or directory.