Docs: Clarify how to stop other ESLint configs from linting package.json files

[Zamiell]

Hello folks,

This plugin is looking in great shape lately, so I decided to try it out in my sharable linting config. However, I found a "gotcha" that I did not expect.

To start with, I am turning on on the plugin like this:

export const basePackageJSON = defineConfig({
  plugins: {
    // @ts-expect-error https://github.com/JoshuaKGoldberg/eslint-plugin-package-json/issues/1242
    "package-json": ESLintPluginPackageJSON,
  },

  files: ["**/package.json"],

  languageOptions: {
    parser: parserJsonc,
    parserOptions: {
      extraFileExtensions: [".json"],
    },
  },

  rules: {
    // [snip]
  },
});

I have found that because of the files line, OTHER ESLint rules will now automatically apply to "package.json" files, which causes errors like this:

Error: Error while loading rule 'isaacscript/no-invalid-default-map': You have used a rule which requires type information, but don't have parserOptions set to generate type information for this file. See https://typescript-eslint.io/getting-started/typed-linting for enabling linting with type information.
Parser: typescript-eslint/parser
Occurred while linting D:\Repositories\isaacscript\packages\isaac-lua-polyfill\package.json

To get around this, I put a ignores: ["**/*.json"] in the blocks where I turn on rules with type information. But the problem with this is that it is not "sharable". What I mean is that, in my sharable ESLint config, if any downstream user extends it and then turns on a rule with type information "on top", then THEY will have to also know about this foot-gun and remember to add on their own copy of ignores: ["**/*.json"]. Yuck!

So, my question is: Is there a trick to enable this plugin but do it in a way that doesn't cause commotion with other ESLint rules?

[michaelfaith]

Unfortunately this is a bit of a gap in ESLint currently. I encountered something similar, recently, when trying to use @eslint/markdown, and raised the question in that repo. The official response from the eslint team was that they recommend using files for all config objects so that you're being very precise about what each config is being applied to: eslint/markdown#517 (comment). I'm not sure if that helps for your case (using files instead of ignores). There's not a whole lot we can do, other than update our documentation.

[JoshuaKGoldberg]

Yeah, this really isn't specific to eslint-plugin-package-json. +1 on updating our docs to be less misleading here. Using files on every config block really is the right way to go.

Conceptually, that actually makes sense to me. There's no longer any sense of a "primary" language for ESLint the way it used to be with JavaScript. It's now a true multi-language (JS/TS, JSON, Markdown, etc.) linter. Every group of rules has a limited set of file extensions (languages) it applies to.

[Zamiell]

Ok, thanks for the quick reply guys!

There's no longer any sense of a "primary" language for ESLint the way it used to be with JavaScript.

Ah, that does make sense. It's super unfortunate though.

There's not a whole lot we can do, other than update our documentation.

Yeah, I think this should definitely get it's own section in the README.md file, maybe a new section called "Gotchas" or something.

This plugin provides some cool rules but right now I'm thinking that linting non-TypeScript files is more trouble than it is worth. =(

[Zamiell]

Oh, here is one more idea that just occurred to me:

One of the main friction points here is that ESLint rules that require type information throw errors when used on a JSON file. But could that be automatically handled in the TSESLint parser itself? In other words, is it possible to do a pull request to typescript-eslint that would make the parser ignore ".json" files in a specific way that would automatically disable any rules that use type information? (This is more of a question for @JoshuaKGoldberg I guess.)

[JoshuaKGoldberg]

could that be automatically handled in the TSESLint parser itself

You could file an issue on typescript-eslint. But I doubt we'd accept it. Sometimes users actually do write custom rules specifically for JSON files that use type info. Example: making sure a file matches some type.

Anyway, this is really a docs issue:

• For this README.md: accepting PRs 👍
• On ESLint core: Docs: Always recommend to include a files property eslint/eslint#20075

[Zamiell]

Here is an update for future readers who are encountering the same difficulties as the OP.

Recently, I stumbled upon a potentially better pattern for linting non-JavaScript/TypeScript files - use a different ESLint configuration file! And then, in your lint script, you invoke ESLint twice, once without specifying a config, and once with specifying the custom config.

Here is an example of a custom ESLint config (this one is actually for linting normal JSON files, not package.json files, but you get the idea):

eslint.config.json.js

// This is the configuration file for ESLint, the TypeScript linter:
// https://eslint.org/docs/latest/use/configure/

// We need to make a separate configuration file for JSON files because JavaScript/TypeScript rules
// will throw errors when applied to JSON files.

// @ts-check

import ESLintPluginJSON from "@eslint/json";
import { defineConfig } from "eslint/config";

export default defineConfig([
  {
    plugins: {
      json: ESLintPluginJSON,
    },

    files: ["**/*.json"],
    language: "json/json",

    // https://github.com/eslint/json?tab=readme-ov-file#rules
    rules: {
      "json/no-duplicate-keys": "error",
      "json/no-empty-keys": "error",
      "json/no-unnormalized-keys": "error",
      "json/no-unsafe-values": "error",
      "json/sort-keys": "error",
      "json/top-level-interop": "error",
    },
  },
]);

This seems like it solves the headaches involved with using ESLint on multiple file types. You keep your core ESLint unchanged, and then you add one ESLint config for your "package.json" files (if you want to lint those), one ESLint config for Markdown files (if you want to lint those), and so on.

Of course, the disadvantage to this pattern is that we have to invoke ESLint multiple times. But I actually don't think this is that big of a deal, because in your TypeScript projects, you typically have a big lint script that runs many individual tools (ESLint, Prettier, knip, cspell, and so on), so adding a second ESLint invocation into the big script fits nicely.

Is anyone else using this pattern? Are there any downsides that I have not considered? I think we might want to make it the recommended way for people to consume the plugin, as we should expect that the average ESLint user is going to have type-aware rules from TSESLint turned on, and that combo will cause pain for first adopters of this plugin.

[michaelfaith]

Interesting idea for sure. I do think that clashes a bit with the ESLint team's recommendation (which is to have files defined on all config objects in a user's config). But it does seem to be a bit easier for people to adopt than having to overhaul their configs to do that. Especially for large, complex configs.

FWIW, here's the migration doc I contributed to the @eslint/markdown repo, after I brought this concern up for that plugin (which suffered from the same issue), and their team was pretty clear in their preference. eslint/markdown#517 -> eslint/markdown#559

[michaelfaith]

We landed on adding this Important box to the doc about that side effect:

Important

Because this plugin uses a new language to power its linting, you may need to update the other configs you're using so that you limit those to only apply to js / ts files.
Otherwise, those rules will be applied to markdown files now, too, which can lead to unexpected failures.

[Zamiell]

Michael,

That GH thread was actually linked already above. But yes, I agree that there are pros and cons here, and it might be best to stick with following the ESLint team's official recommendations.

My personal take: Most shared configs do not (yet) follow this practice, so you end up getting screwed. And even if you don't use any shared configs, it just seems incredibly tedious to type out:

files: ["**/*.js", "**/*.cjs", "**/*.mjs", "**/*.jsx", "**/*.ts", "**/*.cts", "**/*.mts", "**/*.tsx"],

every single time you need to turn on some random rule in a new project. And it's especially annoying/confusing since this boilerplate hasn't been necessary for the past 13 years.

Are there any downsides that I have not considered?

Responding to myself: I realized that a major downside of having multiple config files is that you no longer get ESLint errors in your IDE about JSON files / Markdown files / etc. Very sad. =( Whether that's a deal-breaker I guess depends on how important that is. If all you are doing is linting "package.json" files, then probably not a deal-breaker, but if you are linting hundreds of Markdown files, then it probably would be.