Linter: Use --generate-todo to create a todo list for ignoring rules.

[domingo2000]

Solves #667

Use --generate-todo to create a todo list that will ignore all the current offenses based on an offense count. Very similar of how rubocop does.

The implementation writes to a .herb-todo.yml file, that stores a map of all the files and rules with the counts of offenses and warnings. When the linter runs, reads from that file and ignore all ocurrences declarated as exclude.

The file is not dependant on a Herb Config file, because is autogenerated and can be very big, it should be consider as "private".

The --generate-todo name comes from standardrb recommendation on todo list.

Usage:

herb-lint --regenerate-todo <path> # Creates the file and show the offenses.
herb-lint <path> # Pass the linting without errors nor warnings.

TODO

• Write documentation

[domingo2000]

Passing undefined to let the linter set the default rules is not very idiomatic. Maybe it is better to pass the default rules on each call 🤷🏻 .

[marcoroth]

Maybe we can refactor the Linter to take in an options object as the second argument. So it could be:

Suggested change

	this.linter = new Linter(Herb, undefined, this.linterTodo)
	this.linter = new Linter(Herb, { rules: customRules, linterTodo: this.linterTodo })

or just:

Suggested change

	this.linter = new Linter(Herb, undefined, this.linterTodo)
	this.linter = new Linter(Herb, { linterTodo: this.linterTodo })

[domingo2000]

@marcoroth happy to receive feedback on this. Currently a little WIP and can refactor a little more, but it works well, tried on buk-webapp monolith and is working good (4288 erb files).

Maybe i can follow up this PR with the following:

1. Show how much rules are in .herb-todo.yml
2. Have a command flag that ignore the todo file. This is useful when the you want to get the linter run in all the project, without loosing the current todo.

[domingo2000]

The name is not the best. Maybe TodoList? I belive that just Todo could fit too, but Todo could mean many more things.

[domingo2000]

Should this be --regenerate-todo as rubocop, or --generate-todo as standardrb. I think regenerate makes clear that you are destroying the old one. But generate-todo is a little less verbose and simple.

[marcoroth]

Maybe we can have both so there is no surprise.

--generate-todo can generate a file if none is present yet. If one is present it could back out and say something like: .herb-todo.yml already exists, run "--regenerate-todo" to overwrite it.

--regenerate-todo would just always overwrite the current one, no matter if .herb-todo.yml exists or not.

[marcoroth]

When you run --generate-todo it concludes the run with:

 Rule offenses:
  html-no-space-in-tag (82 offenses in 24 files)
  html-no-self-closing (46 offenses in 3 files)
  html-input-require-autocomplete (27 offenses in 2 files)
  erb-require-trailing-newline (3 offenses in 3 files)


 Summary:
  Checked      210 files
  Files        28 with offenses | 182 clean (210 total)
  Offenses     158 errors | 0 warnings (158 offenses across 28 files)
  Fixable      158 offenses | 131 autocorrectable using `--fix`
  Start at     12:14:46
  Duration     1323ms (40 rules)

Maybe we can mention that we generated a .herb-todo.yml file here too.

On subsequent runs, I think it would also be great to mention the amount of "suppressed offenses", so people are aware that the linter is only passing because of the todos in the .herb-todo.yml file.

❯ herb-lint ../../../../rubyevents

 Summary:
  Checked      210 files
  Files        210 clean (210 total)
  Offenses     0 offenses
  Start at     12:15:49
  Duration     1066ms (40 rules)

 ✓ All files are clean!

[marcoroth]

Another thing (which might not be as common in day-to-day use-cases), but I run the herb-lint out of my current Herb working directory, so I often use relative paths (but this could also happen when you run this within your app).

Running herb-lint ../../../../rubyevents --generate-todo generates the .herb-todo.yml file in the current working directory, and not at ../../../../rubyevents/.herb-todo.yml. I think we might want to resolve the path argument and

a) Put the .herb-todo.yml at the location you provide when running the linter (or if none is provided, use the current working directory like we do now)
b) Look at that path passed when running the linter for a config file first, then in the CWD
c) Inside the .herb-todo.yml: I think the paths should all be relative to the project root, currently they were generated as:

excludes:
  html-no-space-in-tag:
    ../../../../rubyevents/app/views/topics/show.html.erb:
      warning: 0
      error: 1
    ../../../../rubyevents/app/views/templates/new.html.erb:
      warning: 0
      error: 3

# ...

Maybe we can also mention the absolute path of which .herb-todo.yml file the linter is using when running the the linter, something like:

npx herb-lint 

Using TODO Config file at: /Users/[user]/[project]/.herb-todo.yml

Thank you so much for working on this @domingo2000! 🙏🏼