Lint against outdated usages of `helpPagePath`
What does this MR do and why?
As docs pages get moved around or deleted, docs links that we display in
the product might become outdated without us noticing.
This adds an ESLint rule that ensures helpPagePath
always points to
files and anchors that still exist.
In future iterations, we should add a similar rule to check usages of
the HelpPageLink
Vue component, and a Rubocop rule for the backend
help_page_path
helper.
What the rule checks exactly:
- Whether the helper's first argument is passed as a string. Passing it as a variable isn't exactly a problem, but it does however make it harder to lint against improper usages of the linter. When wanting to store a help page path in a constant, it would be preferable to store
helpPagePath
's return value rather than its arguments. - Whether the provided path does correspond to an existing Markdown documentation file.
- Whether the anchor–which can either be provided in the path argument, or in the second argument via the
anchor
property–exists in the Markdown file.
MR acceptance checklist
Please evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.
How to set up and validate locally
-
Break a
helpPagePath
usage in a frontend file, then run ESLint against.-
For example:
diff --git a/app/assets/javascripts/authentication/webauthn/constants.js b/app/assets/javascripts/authentication/webauthn/constants.js index c41e6d2bd587..1b90f17f6fa8 100644 --- a/app/assets/javascripts/authentication/webauthn/constants.js +++ b/app/assets/javascripts/authentication/webauthn/constants.js @@ -41,6 +41,6 @@ export const STATE_WAITING = 'waiting'; export const WEBAUTHN_AUTHENTICATE = 'authenticate'; export const WEBAUTHN_REGISTER = 'register'; export const WEBAUTHN_DOCUMENTATION_PATH = helpPagePath( - 'user/profile/account/two_factor_authentication', + 'user/profile/account/two_factor_authentication/does/not/exist', { anchor: 'set-up-a-webauthn-device' }, );
-
Then run
yarn eslint app/assets/javascripts/authentication/webauthn/constants.js
-
-
OR, lint all frontend files, assuming there are some violations, and they are not ignored:
yarn lint:eslint:all