feat: Prelint plugins #105

nzakas · 2023-02-06T21:42:02Z

Summary

This RFC introduces the concept of a "prelint", which is like a rule but it runs before any linting happens, allowing plugins to modify the behavior of subsequent linting runs.

This requires #99 to function and was split off from that RFC.

Related Issues

#99
eslint/eslint#14745

ljharb · 2023-02-06T22:16:07Z

Does this include a way for a rule to declare a dependency on a prelint, and implicitly "add" it to the prelint list if not already present?

nzakas · 2023-02-06T23:10:59Z

@ljharb no. Rules cannot force users to add other rules, prelints, or configurations. At least to start, rules should specify what they’re expecting in their docs. Plug-ins can, of course, publish configs that contain appropriate “known good” settings.

bradzacher · 2023-02-06T23:49:47Z

designs/2023-prelints/README.md

+
+                context.createVirtualFile({
+                    filename: "0.js",
+                    body: removeIndents(


Slightly off-topic - I would envision that most tools would want to strip indent in the same way - might be good to provide a util from eslint itself that does this?

Certainly worth thinking about -- also worth thinking about: does ESLint just do it automatically for you based on the indentOffset?

Updated the proposal to automatically adjust indents.

ljharb · 2023-02-07T02:38:21Z

Gotcha - that's fine, it just means this doesn't solve the use case of allowing rules to execute a "before" step.

nzakas · 2023-02-07T21:06:31Z

@ljharb is there a specific use case you have in mind?

ljharb · 2023-02-07T21:35:04Z

Yes, I want eslint-plugin-import's rules to be able to indicate that they need an "initialization" step, to cache the module graph, and for eslint to automatically queue up the Promise ordering as appropriate, and to skip the initialization step when no active rules require it.

nzakas · 2023-02-10T20:35:14Z

Ah okay, thanks for the explanation. I'll need to think about that use case a bit more, but I don't think it fits within this RFC.

ota-meshi · 2023-02-12T09:07:30Z

designs/2023-prelints/README.md

+    /**
+     * The number to add to any violations that occur in the first line of
+     * the virtual file. 0 if undefined.
+     */
+    columnStart?: number;
+
+    /**
+     * The number to add to the column number of each violation in the body.
+     * 0 if undefined.
+     */
+    indentOffset?: number;


Is there a way to tell the ESLint engine the negative column offset of a line of text?

For example, if I have HTML like the following (for a 2-space indent), if I want the CSS in the style attribute to have an indentOffset of 4, the font-size will be placed at a column offset of -4.

<div> <div style=" color: red; font-size: 16px; ">

The reason I want to use 4 for indentOffset is because I want to convey the base position for the indent rule. If it's 0, I don't think the indent rule work well. It's probably indented like this:

<div> <div style=" color: red; font-size: 16px; ">

I think people actually want indent like this:

<div> <div style=" color: red; font-size: 16px; ">

Is there a way to tell the ESLint engine the negative column offset of a line of text?

Hmmm, I'm not sure I understand why you'd want to do this. If you have this HTML:

<div> <div style=" color: red; font-size: 16px; ">

And you want to extract the CSS, for linting, I'd think you'd want ESLint to see the CSS as this:

color: red; font-size: 16px;

So you'd say:

context.createVirtualFile({ body: removeIndents(cssNode.text), // get the text you want somehow lineStart: 3, // add this number to any reported lines columnStart: 0, // add this number to any columns reported in the first line indentOffset: 0 // don't adjust indents });

So then you'd take the CSS virtual file, normalize the indents, then that would get merged back into the HTML.

Would that work?

Sorry, I think I didn't explain well 😓. (Prelint may be an unrelated topic.)
How do you think indentation rules for CSS should be implemented to handle indentation correctly given text like this?

<div> <div style=" color: red; font-size: 16px; ">

I would expect it to be indented like this:

<div> <div style=" color: red; font-size: 16px; ">

However, I think the current system would probably indent like this:

<div> <div style=" color: red; font-size: 16px; ">

Because the CSS indentation rules don't know the proper starting position.

I thought it could be solved by indenting based on 0 if a negative column offset could be used, but there may be another way to solve it.

Ah I see what you mean. Indeed, the current design doesn't allow for that. I need to think a bit more about how to handle this.

I think negative indents would be a bit confusing, as a negative indent would mean "add indents" while a positive indent would mean "remove indents".

It might be the case that we need some sort of callback function to allow prelints to further modify a fixed result before inserting into the original file.

I'll think more on this and see what I can come up with.

Okay, so it turns out this will work, just not in the most obvious way.

First, we actually need two different rules, one for CSS and one for HTML. Let's call them css/indent to indent CSS and html/indent to indent HTML.

So to start, we have this code:

<div> <div style=" color: red; font-size: 16px; ">

The prelint would extract the CSS into a text fragment that looks like this:

color: red; font-size: 16px;

The css/indent rule would fix the indentation to this:

color: red; font-size: 16px;

Then, this CSS would be inserted back into the HTML, looking like this:

<div> <div style=" color: red; font-size: 16px; ">

When the html/indent rule then runs, it would end up fixing to this:

<div> <div style=" color: red; font-size: 16px; ">

Basically, we'd be combining the fixes from css/indent and html/indent together either in one pass (if technically possible) or at most in two passes (ESLint does multiple passes when attempting to autofix, so this is not new).

nzakas · 2023-02-13T20:54:01Z

@JamesHenry this RFC might be of interest to you, as well.

JamesHenry · 2023-02-16T07:23:18Z

Thanks @nzakas I can comment on the big 3 projects I work on:

Based on my understanding, I think it would just give an alternative to the use of processors for angular-eslint - I don't think it has any major advantages of the current implementation (but also no major disadvantages)

For typescript-eslint and Nx, I don't think this would change much, I think for those two we would need something much more like what @ljharb is describing

nzakas · 2023-02-16T20:29:24Z

@JamesHenry thanks for the feedback. Indeed, I'm viewing this as a more flexible replacement for processors rather than something radically different. The primary different is that it would allow us to lint both the original file and all of the virtual files, whereas processors only allow linting of virtual files.

nzakas · 2023-02-20T21:01:32Z

Updated to simplify the creation of fragments out of a file. You no longer need to manually manipulate the text before passing it back to ESLint. Let me know what you think.

@eslint/eslint-tsc still waiting for the first round of feedback on this.

mdjermanovic · 2023-03-01T09:40:57Z

designs/2023-prelints/README.md

+}
+```
+
+Each prelint follows the same basic structure of as a rule, only it cannot report violations and instead can only inspect the AST, use `SourceCode` to make any necessary changes, and create fragments as necessary. Otherwise, it looks the same as a rule, such as:


What do we mean by "use SourceCode to make any necessary changes", what kind of changes?

This would be language-dependent. In JavaScript, we have markVariableAsUsed() as an example.

mdjermanovic · 2023-03-01T10:37:54Z

designs/2023-prelints/README.md

+            // prelint with options
+            "markdown/js": {
+                codeBlockTags: ["js", "javascript", "ecmascript"]
+            },


What happens when multiple config entries that specify options for markdown/js match the given file, are the options objects merged or does the last one overwrite previous ones?

Alternatively, since prelints have access to configured settings (PrelintContext.settings), maybe we don't need to support prelint options because they can be specified inside settings for the plugin.

Options are merged in the same way that rule options are merged.

settings has always been a hack and I wouldn't want to lean on it any more.

mdjermanovic · 2023-03-01T11:54:34Z

designs/2023-prelints/README.md

+
+In order to make all of this work, we'll need to make the following changes in the core:
+
+1. `linter.js` will need to be updated to treat fragments the same as processor code blocks (recursively linting) and to do a first traversal of the file using prelints.


linter.js also needs to be updated to postprocess lint messages from fragments? In particular, to calculate locations and fix ranges.

Yes! I'm going to circle back and do some more details around the implementation once I finish up the languages RFC.

brettz9 · 2023-03-20T20:37:20Z

Hi,

Just wanted to confirm--would this support multiple levels of nesting with languages?

My use case would be for @example tags containing JavaScript to lint within a JSDoc block "language" (so that the blocks could have their own AST which rules could target), within the main JavaScript file.

So after parsing the main JavaScript AST, we'd want to find the /** */ blocks and parse their contents as our own JSDoc AST, and then when finding @example within the latter, parse its inner contents again as JavaScript AST.

nzakas · 2023-03-27T19:58:38Z

Yes, based on your config it could go multiple levels deep. So if you have a Markdown file that has a JavaScript block, that would get pulled out, and then any prelints configured for JavaScript files would run. So, if the JavaScript block contained a block of GraphQL, a prelint could pull that out as separate from the Markdown and JavaScript that it was embedded within.

JoshuaKGoldberg · 2024-11-23T17:20:58Z

designs/2023-prelints/README.md

[Question] What about postlint plugins?

Use case: many (most?) projects also configure a formatter such as Prettier alongside ESLint. Many of those projects do so with a separate npm script, separate CI job/workflow, etc. But the intent is to always have formatted code - including after ESLint autofixes or suggestions are applied. It'd be nice to have a way to tell ESLint to always run the formatter after modifying code.

Not really related to this RFC. Please open a separate issue.

eslint/eslint#19171

feat: Prelint plugins

f6f65ad

eslint-github-bot bot added triage feature labels Feb 6, 2023

nzakas mentioned this pull request Feb 6, 2023

feat: ESLint Language Plugins #99

Merged

nzakas added Initial Commenting This RFC is in the initial feedback stage and removed triage labels Feb 6, 2023

bradzacher reviewed Feb 6, 2023

View reviewed changes

ota-meshi reviewed Feb 12, 2023

View reviewed changes

nzakas added 2 commits February 20, 2023 12:53

createVirtualFile -> createTextFragment

b16a7c8

Automatic indent adjustment

9684f2a

mdjermanovic reviewed Mar 1, 2023

View reviewed changes

nzakas mentioned this pull request Dec 8, 2023

Allow processor API to be configurable and to formally be able to lint both a file and its blocks eslint/eslint#14745

Open

nzakas mentioned this pull request Sep 4, 2024

Change Request: Flat Config does not support FileEnumerator eslint/eslint#18087

Open

1 task

nzakas mentioned this pull request Sep 12, 2024

Change Request: Don't pass BOM to preprocess method eslint/eslint#18891

Open

1 task

JoshuaKGoldberg reviewed Nov 23, 2024

View reviewed changes

JoshuaKGoldberg mentioned this pull request Nov 25, 2024

Change Request: Add a concept of "postlint" hooks, such as for running a formatter eslint/eslint#19171

Open

1 task

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Prelint plugins #105

feat: Prelint plugins #105

nzakas commented Feb 6, 2023

ljharb commented Feb 6, 2023

nzakas commented Feb 6, 2023

bradzacher Feb 6, 2023

nzakas Feb 7, 2023

nzakas Feb 20, 2023

ljharb commented Feb 7, 2023

nzakas commented Feb 7, 2023

ljharb commented Feb 7, 2023

nzakas commented Feb 10, 2023

ota-meshi Feb 12, 2023 •

edited

Loading

ota-meshi Feb 12, 2023 •

edited

Loading

nzakas Feb 13, 2023

ota-meshi Feb 14, 2023

nzakas Feb 16, 2023

nzakas Feb 20, 2023

nzakas commented Feb 13, 2023

JamesHenry commented Feb 16, 2023 •

edited

Loading

nzakas commented Feb 16, 2023

nzakas commented Feb 20, 2023

mdjermanovic Mar 1, 2023

nzakas Mar 8, 2023

mdjermanovic Mar 1, 2023

nzakas Mar 8, 2023

mdjermanovic Mar 1, 2023

nzakas Mar 8, 2023

brettz9 commented Mar 20, 2023

nzakas commented Mar 27, 2023

JoshuaKGoldberg Nov 23, 2024

nzakas Nov 25, 2024

JoshuaKGoldberg Nov 25, 2024


		In order to make all of this work, we'll need to make the following changes in the core:

		1. `linter.js` will need to be updated to treat fragments the same as processor code blocks (recursively linting) and to do a first traversal of the file using prelints.

feat: Prelint plugins #105

Are you sure you want to change the base?

feat: Prelint plugins #105

Conversation

nzakas commented Feb 6, 2023

Summary

Related Issues

ljharb commented Feb 6, 2023

nzakas commented Feb 6, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ljharb commented Feb 7, 2023

nzakas commented Feb 7, 2023

ljharb commented Feb 7, 2023

nzakas commented Feb 10, 2023

ota-meshi Feb 12, 2023 • edited Loading

Choose a reason for hiding this comment

ota-meshi Feb 12, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nzakas commented Feb 13, 2023

JamesHenry commented Feb 16, 2023 • edited Loading

nzakas commented Feb 16, 2023

nzakas commented Feb 20, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

brettz9 commented Mar 20, 2023

nzakas commented Mar 27, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ota-meshi Feb 12, 2023 •

edited

Loading

ota-meshi Feb 12, 2023 •

edited

Loading

JamesHenry commented Feb 16, 2023 •

edited

Loading