Bug: [lines-around-comment] afterHashbangComment option is not supported

[EvgenyOrekhov]

Before You File a Bug Report Please Confirm You Have Done The Following...

• I have tried restarting my IDE and the issue persists.
• I have updated to the latest version of the packages.
• I have searched for related issues and found none that matched my issue.
• I have read the FAQ and my problem is not listed.

Playground Link

https://typescript-eslint.io/play/#ts=5.0.1-rc&sourceType=module&code=MQQgZg9hBQBuCGAnABAE3gT2QXmQIgHNEBTeAFz2iA&eslintrc=N4KABGBEBOCuA2BTAzpAXGUEKQAIBcBPABxQGNoBLY-AWhXkoDt8B6RplWgQ2gHtYTACa0yfALbjELdGADa4bDkTR+0SABpFSrEuyRuAM3wqAEt2QALAEbcmAcwDCEqTIz44ibdgC+3gLqKfj5AA&tsconfig=N4KABGBEDGD2C2AHAlgGwKYCcDyiAuysAdgM6QBcYoEEkJemy0eAcgK6qoDCAFutAGsylBm3TgwAXxCSgA

Repro Code

#!foo
var day = "great"

ESLint Config

module.exports = {
  parser: "@typescript-eslint/parser",
  rules: {
    "@typescript-eslint/lines-around-comment": [
      "error",
      {
        "afterHashbangComment": true
      }
    ]
  },
};

tsconfig

{
  "compilerOptions": {
    // ...
  }
}

Expected Result

Should not crash, should warn about missing blank line after hashbang comment

Actual Result

Configuration for rule "@typescript-eslint/lines-around-comment" is invalid:
Value {"afterHashbangComment":true,"beforeBlockComment":true,"afterBlockComment":false,"beforeLineComment":false,"afterLineComment":false,"allowBlockStart":false,"allowBlockEnd":false} should NOT have additional properties.

Additional Info

The playground example doesn't crash, but CLI crashes.

[IronGeek]

I can confirm this issue.

According to the eslint changelog, the afterHashbangComment options for eslint/lines-around-comment rule is only recently added in v8.35.0

And if we look at the latest https://github.com/typescript-eslint source:

typescript-eslint/packages/eslint-plugin/src/rules/lines-around-comment.ts

Lines 54 to 136 in a1a20b3

	schema: {
	type: 'array',
	items: [
	{
	type: 'object',
	properties: {
	beforeBlockComment: {
	type: 'boolean',
	default: true,
	},
	afterBlockComment: {
	type: 'boolean',
	default: false,
	},
	beforeLineComment: {
	type: 'boolean',
	default: false,
	},
	afterLineComment: {
	type: 'boolean',
	default: false,
	},
	allowBlockStart: {
	type: 'boolean',
	default: false,
	},
	allowBlockEnd: {
	type: 'boolean',
	default: false,
	},
	allowClassStart: {
	type: 'boolean',
	},
	allowClassEnd: {
	type: 'boolean',
	},
	allowObjectStart: {
	type: 'boolean',
	},
	allowObjectEnd: {
	type: 'boolean',
	},
	allowArrayStart: {
	type: 'boolean',
	},
	allowArrayEnd: {
	type: 'boolean',
	},
	allowInterfaceStart: {
	type: 'boolean',
	},
	allowInterfaceEnd: {
	type: 'boolean',
	},
	allowTypeStart: {
	type: 'boolean',
	},
	allowTypeEnd: {
	type: 'boolean',
	},
	allowEnumStart: {
	type: 'boolean',
	},
	allowEnumEnd: {
	type: 'boolean',
	},
	allowModuleStart: {
	type: 'boolean',
	},
	allowModuleEnd: {
	type: 'boolean',
	},
	ignorePattern: {
	type: 'string',
	},
	applyDefaultIgnorePatterns: {
	type: 'boolean',
	},
	},
	additionalProperties: false,
	},
	],
	},

We can see that the afterHashbangComment is not yet supported (not yet added to @typescript-eslint/lines-around-comment schema).

---

On a side note, I just noticed by reading the source, apparently there's more options for the @typescript-eslint/lines-around-comment that is not mentioned in the docs:

• allowEnumStart
• allowEnumEnd
• allowModuleStart
• allowModuleEnd

Is these options meant to be supported?

[JoshuaKGoldberg]

Yup, ESLint core added an afterHashbagComment option that we don't yet have here. Accepting PRs.

more options

Good spot, I'll send a PR to fix up those docs now. Thanks!

[kozlovvski]

@JoshuaKGoldberg I'd like to fix this, however this requires eslint@8.35.0. Since we have "eslint": "^8.15.0" in our package.json, how should I approach this? Should my PR bump the eslint version?

Context:
We use the base eslint rule for the comments in the start/end of the block – we could leverage the same behavior for shebang comments as well. However, we would need the newer version of eslint, which supports the afterHashbangComment option.

[JoshuaKGoldberg]

Hmm I actually don't know what to do in this situation. @bradzacher?

[bradzacher]

Given the rule is an extension rule and not a fork - really the schema for the rule should be based off of the base rule's schema and we just add our additional options to the schema. That way we aren't allowing options that aren't supported in the base implementation.

[kozlovvski]

Given the rule is an extension rule and not a fork - really the schema for the rule should be based off of the base rule's schema and we just add our additional options to the schema. That way we aren't allowing options that aren't supported in the base implementation.

Sorry, I am unsure what this means in the afterHashbangComment case. Should the logic work as following?

1. If the user has a version of eslint supporting the new option, allow this option in the matching typescript-eslint rule and use base rule process to handle it
2. Otherwise, don't allow the option.

[bradzacher]

If the user has a version of eslint supporting the new option, allow this option in the matching typescript-eslint rule and use base rule process to handle it

Correct. Currently the schema is hard-coded:

typescript-eslint/packages/eslint-plugin/src/rules/lines-around-comment.ts

Lines 54 to 136 in aa537e5

	schema: {
	type: 'array',
	items: [
	{
	type: 'object',
	properties: {
	beforeBlockComment: {
	type: 'boolean',
	default: true,
	},
	afterBlockComment: {
	type: 'boolean',
	default: false,
	},
	beforeLineComment: {
	type: 'boolean',
	default: false,
	},
	afterLineComment: {
	type: 'boolean',
	default: false,
	},
	allowBlockStart: {
	type: 'boolean',
	default: false,
	},
	allowBlockEnd: {
	type: 'boolean',
	default: false,
	},
	allowClassStart: {
	type: 'boolean',
	},
	allowClassEnd: {
	type: 'boolean',
	},
	allowObjectStart: {
	type: 'boolean',
	},
	allowObjectEnd: {
	type: 'boolean',
	},
	allowArrayStart: {
	type: 'boolean',
	},
	allowArrayEnd: {
	type: 'boolean',
	},
	allowInterfaceStart: {
	type: 'boolean',
	},
	allowInterfaceEnd: {
	type: 'boolean',
	},
	allowTypeStart: {
	type: 'boolean',
	},
	allowTypeEnd: {
	type: 'boolean',
	},
	allowEnumStart: {
	type: 'boolean',
	},
	allowEnumEnd: {
	type: 'boolean',
	},
	allowModuleStart: {
	type: 'boolean',
	},
	allowModuleEnd: {
	type: 'boolean',
	},
	ignorePattern: {
	type: 'string',
	},
	applyDefaultIgnorePatterns: {
	type: 'boolean',
	},
	},
	additionalProperties: false,
	},
	],
	},

Instead of it being hard-coded it should be described in relation to the base rule's schema so that it exposes the same options the base rule does.

[kozlovvski]

Okay, I will try to fix this 🙌🏻

[bradzacher]

Hi there 👋!

As you may have heard ESLint core is deprecating its formatting rules. We are likewise moving in the same direction and deprecating our formatting rules.

Deprecated rules will be removed in the next major version as their new home is the eslint-stylistic project.

If this issue is important to you please consider filling an issue over at eslint-stylistic which will be the new home for stylistic/formatting rules.

Thanks!