Merge pull request #2268 from github/markdown-lint-local

koesie10 · web-flow · commit 5d7d1b25abac · 2023-04-05T16:41:40.000+02:00
Set up markdownlint with GitHub's additional rules in VSCode and as npm script
diff --git a/.markdownlint.json b/.markdownlint.json
@@ -0,0 +1,4 @@
+{
+  "MD013": false,
+  "MD041": false
+}
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
@@ -4,6 +4,7 @@
   // List of extensions which should be recommended for users of this workspace.
   "recommendations": [
     "amodio.tsl-problem-matcher",
+    "DavidAnson.vscode-markdownlint",
     "dbaeumer.vscode-eslint",
     "esbenp.prettier-vscode",
     "firsttris.vscode-jest-runner",
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -43,6 +43,30 @@
     "TZ": "UTC"
   },
 
+  // These custom rules are read in extensions/ql-vscode/.markdownlint-cli2.cjs
+  // but markdownlint only considers that config when linting files in
+  // extensions/ql-vscode/ or its subfolders. Therefore, we have to explicitly
+  // load the custom rules here too.
+  "markdownlint.customRules": [
+    "./extensions/ql-vscode/node_modules/@github/markdownlint-github/src/rules/no-default-alt-text.js",
+    "./extensions/ql-vscode/node_modules/@github/markdownlint-github/src/rules/no-generic-link-text.js"
+  ],
+
+  // This ensures that the accessibility rule enablement done by github-markdownlint is
+  // considered by the extension too.
+  //
+  // Unfortunately, we can only specify a single extends, so the config here isn't
+  // identical since it can't also consider @github/markdownlint-github/style/base.json
+  // That's not as bad as it could be since the full config is considered for anything
+  // in extensions/ql-vscode/ or its subfolders anyway.
+  //
+  // Additional nonfiguration of the default rules is done in .markdownlint.json,
+  // which is picked up by the extension automatically, and read explicitly in
+  // .markdownlint-cli2.cjs
+  "markdownlint.config": {
+    "extends": "./extensions/ql-vscode/node_modules/@github/markdownlint-github/style/accessibility.json"
+  },
+
   // These options are used by the `jestrunner.debug` command.
   // They are not used by the `jestrunner.run` command.
   // After clicking "debug" over a test, continually invoke the
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -67,10 +67,7 @@ members of the project's leadership.
 
 ## Attribution
 
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
-available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
-
-[homepage]: https://www.contributor-covenant.org
+This Code of Conduct is adapted from the [Contributor Covenant, version 1.4](https://www.contributor-covenant.org/version/1/4/code-of-conduct.html).
 
 For answers to common questions about this code of conduct, see
-https://www.contributor-covenant.org/faq
+[the Contributor Covenant FAQ](https://www.contributor-covenant.org/faq). For more about Contributor Covenant, see [the Contributor Covenant website](https://www.contributor-covenant.org).
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -23,7 +23,9 @@ Please note that this project is released with a [Contributor Code of Conduct][c
 Here are a few things you can do that will increase the likelihood of your pull request being accepted:
 
 * Follow the [style guide][style].
-* Write tests. Tests that don't require the VS Code API are located [here](extensions/ql-vscode/test). Integration tests that do require the VS Code API are located [here](extensions/ql-vscode/src/vscode-tests).
+* Write tests:
+  * [Tests that don't require the VS Code API are located here](extensions/ql-vscode/test).
+  * [Integration tests that do require the VS Code API are located here](extensions/ql-vscode/src/vscode-tests).
 * Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests.
 * Write a [good commit message](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
 
@@ -93,7 +95,7 @@ More information about Storybook can be found inside the **Overview** page once
 
 ### Testing
 
-Information about testing can be found [here](./docs/testing.md).
+[Information about testing can be found here](./docs/testing.md).
 
 ## Resources
 
diff --git a/LICENSE.md b/LICENSE.md
@@ -17,4 +17,4 @@ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/README.md b/README.md
@@ -25,8 +25,8 @@ This project will track new feature development in CodeQL and, whenever appropri
 
 This extension depends on the following two extensions for required functionality. They will be installed automatically when you install VS Code CodeQL.
 
-- [Test Adapter Converter](https://marketplace.visualstudio.com/items?itemName=ms-vscode.test-adapter-converter)
-- [Test Explorer UI](https://marketplace.visualstudio.com/items?itemName=hbenl.vscode-test-explorer)
+* [Test Adapter Converter](https://marketplace.visualstudio.com/items?itemName=ms-vscode.test-adapter-converter)
+* [Test Explorer UI](https://marketplace.visualstudio.com/items?itemName=hbenl.vscode-test-explorer)
 
 ## Contributing
 
diff --git a/docs/releasing.md b/docs/releasing.md
@@ -12,8 +12,8 @@
       * Accumulation of many changes, none of which are individually big enough to warrant a minor bump, but which together are. This does not include changes which are purely internal to the extension, such as refactoring, or which are only available behind a feature flag.
 1. Double-check that the node version we're using matches the one used for VS Code. If it doesn't, you will then need to update the node version in the following files:
     * `.nvmrc` - this will enable `nvm` to automatically switch to the correct node version when you're in the project folder
-    * `.github/workflows/main.yml` - all the "node-version: <version>" settings
-    * `.github/workflows/release.yml` - the "node-version: <version>" setting
+    * `.github/workflows/main.yml` - all the "node-version: '[VERSION]'" settings
+    * `.github/workflows/release.yml` - the "node-version: '[VERSION]'" setting
 1. Double-check that the extension `package.json` and `package-lock.json` have the version you intend to release. If you are doing a patch release (as opposed to minor or major version) this should already be correct.
 1. Create a PR for this release:
     * This PR will contain any missing bits from steps 1, 2 and 3. Most of the time, this will just be updating `CHANGELOG.md` with today's date.
@@ -22,23 +22,26 @@
     * Create a PR for this branch.
     * Wait for the PR to be merged into `main`
 1. Switch to `main` branch and pull latest changes
-1. Lock the `main` branch. 
+1. Lock the `main` branch.
     * Go to the [branch protection rules for the `main` branch](https://github.com/github/vscode-codeql/settings/branch_protection_rules/16447115)
     * Select "Lock branch"
     * Click "Save changes"
 1. Ensure that no PRs have been merged since the release PR that you merged. If there were, you might need to unlock `main` temporarily and update the CHANGELOG again.
 1. Build the extension `npm run build` and install it on your VS Code using "Install from VSIX".
 1. Go through [our test plan](./test-plan.md) to ensure that the extension is working as expected.
 1. Switch to `main` and add a new tag on the `main` branch with your new version (named after the release), e.g.
+
     ```bash
     git checkout main
     git tag v1.3.6
     ```
 
    If you've accidentally created a badly named tag, you can delete it via
-    ```bash
-    git tag -d badly-named-tag
-    ```
+
+   ```bash
+   git tag -d badly-named-tag
+   ```
+
 1. Unlock the main branch
     * Go to the [branch protection rules for the `main` branch](https://github.com/github/vscode-codeql/settings/branch_protection_rules/16447115)
     * Deselect "Lock branch"
@@ -68,7 +71,7 @@
    or look at the source if there's any doubt the right code is being shipped.
 1. Install the `.vsix` file into your vscode IDE and ensure the extension can load properly. Run a single command (like run query, or add database).
 1. Go to the actions tab of the vscode-codeql repository and select the [Release workflow](https://github.com/github/vscode-codeql/actions?query=workflow%3ARelease).
-    - If there is an authentication failure when publishing, be sure to check that the authentication keys haven't expired. See below.
+    * If there is an authentication failure when publishing, be sure to check that the authentication keys haven't expired. See below.
 1. Approve the deployments of the correct Release workflow. This will automatically publish to Open VSX and VS Code Marketplace.
 1. Go to the draft GitHub release in [the releases tab of the repository](https://github.com/github/vscode-codeql/releases), click 'Edit', add some summary description, and publish it.
 1. Confirm the new release is marked as the latest release at <https://github.com/github/vscode-codeql/releases>.
diff --git a/docs/test-plan.md b/docs/test-plan.md
@@ -83,6 +83,7 @@ choose to go through some of the Optional Test Cases.
 ### Test Case 5: MRVA - Canceling a variant analysis run
 
 Run one of the above MRVAs, but cancel it from within VS Code:
+
 - Check that the query is canceled and the query history item is updated.
 - Check that the workflow run is also canceled.
 - Check that any available results are visible in VS Code.
@@ -231,6 +232,7 @@ with this since it has quite a limited number of actions you can do.
 
 This requires running a MRVA query and seeing the results view.
 
+<!-- markdownlint-disable-next-line MD024 -->
 #### Test case 1: When variant analysis state is "pending"
 
 1. Can open a results view
diff --git a/docs/testing.md b/docs/testing.md
@@ -18,6 +18,7 @@ Any test data you're using (sample projects, config files, etc.) must go in a `t
 ## Running the tests
 
 Pre-requisites:
+
 1. Run `npm run build`.
 2. You will need to have `npm run watch` running in the background.
 
@@ -29,7 +30,7 @@ Then, from the `extensions/ql-vscode` directory, use the appropriate command to
 * View Tests: `npm test:view`
 * VSCode integration tests: `npm run test:vscode-integration`
 
-#### CLI integration tests
+#### Running CLI integration tests from the terminal
 
 The CLI integration tests require the CodeQL standard libraries in order to run so you will need to clone a local copy of the `github/codeql` repository.
 
@@ -51,7 +52,7 @@ You will need to run tests using a task from inside of VS Code, under the "Run a
 * View Tests: run the _Launch Unit Tests_ task
 * VSCode integration tests: run the _Launch Unit Tests - No Workspace_ and _Launch Unit Tests - Minimal Workspace_ tasks
 
-#### CLI integration tests
+#### Running CLI integration tests from VSCode
 
 The CLI integration tests require the CodeQL standard libraries in order to run so you will need to clone a local copy of the `github/codeql` repository.
 
@@ -63,7 +64,7 @@ The CLI integration tests require the CodeQL standard libraries in order to run
 
 ## Running a single test
 
-### 1. From the terminal
+### 1. Running a single test from the terminal
 
 The easiest way to run a single test is to change the `it` of the test to `it.only` and then run the test command with some additional options
 to only run tests for this specific file. For example, to run the test `test/vscode-tests/cli-integration/run-queries.test.ts`:
@@ -78,7 +79,7 @@ You can also use the `--testNamePattern` option to run a specific test within a
 npm run test:cli-integration -- --runTestsByPath test/vscode-tests/cli-integration/run-queries.test.ts --testNamePattern "should create a QueryEvaluationInfo"
 ```
 
-### 2. From VSCode
+### 2. Running a single test from VSCode
 
 Alternatively, you can run a single test inside VSCode. To do so, install the [Jest Runner](https://marketplace.visualstudio.com/items?itemName=firsttris.vscode-jest-runner) extension. Then,
 you will have quicklinks to run a single test from within test files. To run a single unit or integration test, click the "Run" button. Debugging a single test is currently only supported
@@ -94,7 +95,9 @@ Multi-Repo Variant Analyses (MRVA) rely on the GitHub API. In order to make deve
 ### Using a pre-recorded test scenario
 
 To run a mock MRVA scenario, follow these steps:
+
 1. Enable the mock GitHub API server by adding the following in your VS Code user settings (which can be found by running the `Preferences: Open User Settings (JSON)` VS Code command):
+
 ```json
 "codeQL.mockGitHubApiServer": {
   "enabled": true
@@ -108,9 +111,11 @@ To run a mock MRVA scenario, follow these steps:
 If you want to replay the same scenario you should unload and reload it so requests are replayed from the start.
 
 ### Recording a new test scenario
+
 To record a new mock MRVA scenario, follow these steps:
 
 1. Enable the mock GitHub API server by adding the following in your VS Code user settings (which can be found by running the `Preferences: Open User Settings (JSON)` VS Code command):
+
 ```json
 "codeQL.mockGitHubApiServer": {
   "enabled": true
diff --git a/extensions/ql-vscode/.markdownlint-cli2.cjs b/extensions/ql-vscode/.markdownlint-cli2.cjs
@@ -0,0 +1,16 @@
+// Having the base options in a top-level config file means
+// that the VS Code markdownlint extension can pick them up
+// too, since that only considers _this_ file when looking
+// at files in this directory or below.
+base_options = require('../../.markdownlint.json')
+
+const options = require('@github/markdownlint-github').init(
+  base_options
+)
+module.exports = {
+    config: options,
+    customRules: ["@github/markdownlint-github"],
+    outputFormatters: [
+      [ "markdownlint-cli2-formatter-pretty", { "appendLink": true } ] // ensures the error message includes a link to the rule documentation
+    ]
+} 
diff --git a/extensions/ql-vscode/README.md b/extensions/ql-vscode/README.md
@@ -28,7 +28,7 @@ For information about other configurations, see the separate [CodeQL help](https
 1. [Run a query](#running-a-query).
 
 ---
-
+<!-- markdownlint-disable-next-line MD024 -->
 ## Quick start: Installing and configuring the extension
 
 ### Installing the extension
@@ -71,6 +71,7 @@ in the starter workspace directory.
 
 If you're using your own clone of the CodeQL standard libraries, you can do a `git pull` from where you have the libraries checked out.
 
+<!-- markdownlint-disable-next-line MD024 -->
 ## Quick start: Using CodeQL
 
 You can find all the commands contributed by the extension in the Command Palette (**Ctrl+Shift+P** or **Cmd+Shift+P**) by typing `CodeQL`, many of them are also accessible through the interface, and via keyboard shortcuts.
diff --git a/extensions/ql-vscode/package-lock.json b/extensions/ql-vscode/package-lock.json
diff --git a/extensions/ql-vscode/package.json b/extensions/ql-vscode/package.json
diff --git a/extensions/ql-vscode/src/stories/Overview.stories.mdx b/extensions/ql-vscode/src/stories/Overview.stories.mdx

-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +{
 +  "MD013": false,
 +  "MD041": false
 +}