Implement a Linter Framework

[cadeef]

As the project grows, code quality and standards enforcement will become important. This is a stub issue for discussion of linter frameworks that might handle immediate needs and facilitate long-term possibilities.

• What are the compelling options currently in the space?
• What are current/future needs?
• Are there more esoteric requirements that should guide a decision?

[tcort]

jshint is currently run during npm test (as part of the pretest script in package.json). Are there issues that it misses that other linters would detect?

[cadeef]

The notion with linters is work smarter not harder. JSHint may satisfactorily lint JS (I'd yield to anyone who knows more about JS than I on that), but there are lot's of other aspects of a project worth linting. For instance, the repo is filled with YAML files, wouldn't it be nice to have commit or merge time validation checks? A full linting framework permits validation across the project so that you don't have think about "does this maintain our standard" or "is this valid?" It's good hygiene.

[nvuillam]

General requirement

• Make sure all code published in markdown-lint-check is clean and follows coding/formatting best practices

Mega-Linter

Demo PR in this repo (without fixes): https://github.com/nvuillam/markdown-link-check/pull/2 Demo PR in this repo (with fixes): https://github.com/tcort/markdown-link-check/pull/137

Pros:

• 100% free and open-source
• Checks all language, but also formats ( XML, JSON, YAML ) out of the box
• Based on heavily used Github Super Linter (6k stars), but with much more features (https://nvuillam.github.io/mega-linter/#mega-linter-vs-super-linter)
• Everything happening on Github Actions servers, not on a remote black box cloning the repo
• Easy logs browsing
• Can automatically (or manually) apply formatting and fixes
• Always using the latest version of all linters
• Easy configuration to activate/deactivate linters, or define them as non-blocking
• Same config files used by locally installed linters
• Also checks abusive copy-pastes and spelling mistakes (those checks can be disabled if wished)
• Not happy with it ? Just delete github/workflows/mega-linter.yml

Cons:

• No very known yet (but seriously maintained)
• Docker image based, so no "easy" local run yet (but linters used can be individually added thanks to centralized documentation)
• No UI except inside GitHub and in (organized) artifact logs

Other cloud code quality tools:

Sonar , Codacy, CodeClimate ...

Pros

• Online UI
• Maturity
• Free for open source use

Cons

• Need to go outside of github to check links
• No auto-formatting and auto-fixing
• No local run

Individual linters

Install and configure one by one the linters then call them locally and thru CI

Pros

• Same linter commands runned locally and on CI

Cons

• More setup time and more maintenance
• Need to manually upgrade linters versions (PR can be generated via dependabot)

Summary

So, not surprisingly , I will propose Mega-Linter , for all the pros :)

Note: All available propositions provide a better developer experience in case of use of related linters extensions in the developer IDEs (ex: eslint for VsCode), so that errors can be directly detected while writing, instead of when running tests, committing and pushing

I obviously may not be objective, do not hesitate to add more pros & cons to the available choices :)

[cadeef]

I like Pre-commit. I use it extensively both personally and professionally. It has a number of things going for it:

• Mature. It has been around for ages and is stable with new features released routinely. I’ve seen very few if any critical, breaking bugs in the time I’ve used it.
• Active and experienced development team. Not only active but experienced, the core team are the same folks who maintain pytest & tox-- major python projects
• Language agnostic and batteries included. Write lints in virtually any language that suits, there’s a full internal framework for installing tools.
• Large, community-driven directory of existing hooks. Even if what you’re looking for isn’t available in the directory, most linters are GitHub search away.
• Git-first. It was designed around git hooks and can trigger on virtually every available hook. For instance, I trigger a test run pre-push on most repos to ensure that I’m not pushing breaking code.
• Easy to install. A struggle with many tools of this sort is getting them installed, pre-commit is available for install from most package managers.
• Adding additional checks is dead simple. It uses a single config file per repository.
• GitHub Workflow support already exists. There’s little work adding it existing CI.

I’ve surely missed something glaring, and will update the comment if it comes to mind.

[cadeef]

@nvuillam Probably my biggest concern with Mega-Linter is that you describe it as a hard fork, but the documented plans for the project suggest a full port to python. Ports can be difficult, and stabilizing them even more so. I'm not sure I understand the reason for a port of super-linter other than language preference/learning.

[nvuillam]

@cadeef > bash vs python... it's not just about languages, more about capabilities, that are dramatically increased thanks to python modules :) It's by seing the huge amount of copy pastes and complex code in bash , and struggling to implement evolutions, that I proposed the python refactoring (that Super-Linter maintainers sadly rejected, after long internal discussions)

It is already fully ported to python (the remaining sh files are used only in internal CI, and to check differencies when periodically refreshing from base repo

I hear you about the "no easy local run = deal breaker", i think i'll implement some wrapper in a npm package that would run on a .mega-linter.yml using config file at the root of the repo (no matter if mega-linter is selected for markdown-link-check or not ! )

[cadeef]

@nvuillam I'm sure there's interesting conversation to be had about your justification for porting, but probably not in this thread, feel free to email me if you'd like to continue (I might have some battle-hardened perspective for you).

[nvuillam]

FYI, Mega-Linter is now locally runnable locally :)

https://nvuillam.github.io/mega-linter/mega-linter-runner/

May I wake upgrade https://github.com/tcort/markdown-link-check/pull/137 ? :)