Markdown linting support (#159)

.github/workflows/hygeine.yml

@@ -37,3 +37,21 @@ jobs:
         with:
           # Optional: version of golangci-lint to use in form of v1.2 or v1.2.3 or `latest` to use the latest version
           version: v1.52.1
+
+  markdown-linting:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Check out code
+      uses: actions/checkout@v3
+
+    - name: Set up Node.js
+      uses: actions/setup-node@v2
+      with:
+        node-version: '14' 
+
+    - name: Install markdownlint CLI
+      run: npm install -g markdownlint-cli
+
+    - name: Run markdownlint
+      run: markdownlint '**/*.md'

.markdownlint.json

@@ -0,0 +1,4 @@
+{
+    "MD013": false
+}
+

CONTRIBUTING.md

@@ -11,12 +11,12 @@ Coinbase projects.
 
 ## Before You Start
 
-Ensure that you have read and understand the project's README file and the 
+Ensure that you have read and understand the project's README file and the
 contribution guidelines. Search the issues tracker to see if the issue you
 want to work on has already been reported or if someone is already working
 on it. If you find an existing issue that you would like to work on, request
 to be assigned to the issue. If you cannot find an existing issue that matches
-what you want to work on, create a new issue and wait for it to be assigned to 
+what you want to work on, create a new issue and wait for it to be assigned to
 you before starting work on it.
 
 ## Bug Reports
@@ -51,19 +51,19 @@ The best way to see a feature added, however, is to submit a pull request.
 
 * Ensure that your code is well-documented and meets the project's coding standards.
 
-* Provide a reference to the issue you worked on and provide a brief description of the
-  changes you made.
+* Provide a reference to the issue you worked on and provide a brief description
+of the changes you made.
 
 * Submit your pull request!
 
 ## Contributing to an Existing Issue
 
-If you have been assigned an issue, please confirm that the issue is still open 
+If you have been assigned an issue, please confirm that the issue is still open
 and has not already been resolved. If you have any questions about the issue,
 please ask on the issue thread before starting work on it. Once you are assigned
 to an issue, you can start working on a solution for it. Please note that it
 is important to communicate regularly with the project maintainers and update
-them on your progress. If you are no longer able to work on an issue, please 
+them on your progress. If you are no longer able to work on an issue, please
 let us know as soon as possible so we can reassign it.
 
 ## Support Requests
@@ -76,4 +76,4 @@ All support requests must be made via [our support team][3].
 
 [1]: https://github.com/base-org/pessimism/issues
 [2]: https://medium.com/brigade-engineering/the-secrets-to-great-commit-messages-106fc0a92a25
-[3]: https://support.coinbase.com/customer/en/portal/articles/2288496-how-can-i-contact-coinbase-support-
+[3]: https://support.coinbase.com/customer/en/portal/articles/2288496-how-can-i-contact-coinbase-support-

README.md

@@ -1,7 +1,12 @@
 # pessimism
-__Because you can't always be optimistic__
 
-_Pessimism_ is a public good monitoring service that allows for [OP Stack](https://stack.optimism.io/) and EVM compatible blockchains to be continuously assessed for real-time threats using custom defined user heuristic rule sets. To learn about Pessimism's architecture, please advise the documentation. 
+## Because you can't always be optimistic
+
+_Pessimism_ is a public good monitoring service that allows for [OP Stack](https://stack.optimism.io/)
+and EVM compatible blockchains to be
+continuously assessed for real-time threats using custom defined
+user heuristic rule sets. To learn about Pessimism's architecture,
+please advise the documentation.
 
 <!-- Badge row 1 - status -->
 
@@ -17,78 +22,122 @@ _Pessimism_ is a public good monitoring service that allows for [OP Stack](https
 [![GitHub Issues](https://img.shields.io/github/issues-raw/base-org/pessimism.svg)](https://github.com/base-org/pessimism/issues)
 
 **Warning:**
-Pessimism is currently experimental and very much in development. It means Pessimism is currently unstable, so code will change and builds can break over the coming months. If you come across problems, it would help greatly to open issues so that we can fix them as quickly as possible.
+Pessimism is currently experimental and very much in development. It means
+Pessimism is currently unstable, so code will change and builds can break
+over the coming months. If you come across problems, it would help greatly
+to open issues so that we can fix them as quickly as possible.
 
 ## Setup
+
 To use the template, run the following command(s):
+
 1. Create local config file (`config.env`) to store all necessary environmental variables. There's already an example `config.env.template` in the repo that stores default env vars.
 
 2. [Download](https://go.dev/doc/install) or upgrade to `golang 1.19`.
 
 3. Install all project golang dependencies by running `go mod download`.
 
-# To Run
+## To Run
+
 1. Compile pessimism to machine binary by running the following project level command(s):
     * Using Make: `make build-app`
 
 2. To run the compiled binary, you can use the following project level command(s):
     * Using Make: `make run-app`
     * Direct Call: `./bin/pessimism`
 
-
 ## Docker
+
 1. Ensure [docker](https://docs.docker.com/engine/install/) is installed on your machine
 
 2. Pull the latest image from Github container registry (ghcr) via `docker pull ghcr.io/base-org/pessimism:latest`
 
 3. Make sure you have followed the above instructions to create a local config file (config.env) using the config.env.template
 
 4. Run the following:
-   * Without genesis.json: 
+   * Without genesis.json:
+
    ```bash
    docker run -p 8080:8080 -p 7300:7300 --env-file=config.env -it ghcr.io/base-org/pessimism:latest
    ```
-   * With genesis.json: 
+
+   * With genesis.json:
+
    ```bash
    docker run -p 8080:8080 -p 7300:7300 --env-file=config.env -it -v ${PWD}/genesis.json:/app/genesis.json ghcr.io/base-org/pessimism:latest
    ```
 
 **Note**: If you want to bootstrap the application and run specific heuristics/pipelines upon start, update config.env `BOOTSTRAP_PATH` value to the location of your genesis.json file then run
 
 ### Building and Running New Images
-- Run `make docker-build` at the root of the repository to build a new docker image.
-
-- Run `make docker-run` at the root of the repository to run the new docker image.
 
+* Run `make docker-build` at the root of the repository to build a new docker image.
 
+* Run `make docker-run` at the root of the repository to run the new docker image.
 
 ## Linting
-[golangci-lint](https://golangci-lint.run/) is used to perform code linting. Configurations are defined in [.golangci.yml](./.golangci.yml)
+
+[golangci-lint](https://golangci-lint.run/) is used to perform code linting.
+Configurations are defined in [.golangci.yml](./.golangci.yml)
 It can be ran using the following project level command(s):
+
 * Using Make: `make lint`
 * Direct Call: `golangci-lint run`
 
+## Linting Markdown Files
+
+To ensure consistent formatting and avoid common mistakes in our Markdown documents,
+we use markdownlint. Before submitting a pull request, you can check your Markdown
+files for compliance.
+
+### Installation
+
+1. **Install Node.js**:
+If you haven't already, install [Node.js](https://nodejs.org/en).
+
+2. **Install markdownlint CLI globally**:
+
+```bash
+npm install -g markdownlint-cli
+```
+
+### Linting with markdownlint
+
+To lint your Markdown files, navigate to the root directory of the project and run:
+
+```bash
+markdownlint '**/*.md'
+```
+
+If markdownlint reports any issues, please fix them before submitting your pull request.
+
 ## Testing
 
 ### Unit Tests
+
 Unit tests are written using the native [go test](https://pkg.go.dev/testing) library with test mocks generated using the golang native [mock](https://github.com/golang/mock) library. These tests live throughout the project's `/internal` directory and are named with the suffix `_test.go`.
 
 Unit tests can run using the following project level command(s):
+
 * Using Make: `make test`
 * Direct Call: `go test ./...`
 
 ### Integration Tests
+
 Integration tests are written that leverage the existing [op-e2e](https://github.com/ethereum-optimism/optimism/tree/develop/op-e2e) testing framework for spinning up pieces of the bedrock system. Additionally, the [httptest](https://pkg.go.dev/net/http/httptest) library is used to mock downstream alerting services (e.g. Slack's webhook API). These tests live in the project's `/e2e` directory.
 
 Integration tests can run using the following project level command(s):
+
 * Using Make: `make e2e-test`
 * Direct Call: `go test ./e2e/...`
 
 ## Bootstrap Config
+
 A bootstrap config file is used to define the initial state of the pessimism service. The file must be `json` formatted with its directive defined in the `BOOTSTRAP_PATH` env var. (e.g. `BOOTSTRAP_PATH=./genesis.json`)
 
 ### Example File
-```
+
+```json
 [
     {
         "network": "layer1",
@@ -122,6 +171,6 @@ A bootstrap config file is used to define the initial state of the pessimism ser
 ]
 ```
 
-
 ## Spawning a heuristic session
+
 To learn about the currently supported heuristics and how to spawn them, please advise the [heuristics' documentation](./docs/heuristics.markdown).

SECURITY.md

@@ -1,6 +1,7 @@
 # Pessimism Security Policy
 
 ## Reporting a Security Bug
+
 If you think you have discovered a security issue within any part of this codebase, please let us know. We take security bugs seriously; upon investigating and confirming one, we will patch it within a reasonable amount of time, and ultimately release a public security bulletin, in which we discuss the impact and credit the discoverer.
 
-Report your findings to our H1 program: https://hackerone.com/coinbase
+Report your findings to our H1 program: <https://hackerone.com/coinbase>

docs/README.md

@@ -1,8 +1,9 @@
 # Pessimism Documentation
 
-This directory contains the english specs for the Pessimism application. 
+This directory contains the english specs for the Pessimism application.
 
 ## Contents
+
 - [Architecture](architecture/architecture.markdown)
 - [JSON-RPC API](swaggerdoc.html)
 - [ETL Subsystem](architecture/etl.markdown)
@@ -12,41 +13,59 @@ This directory contains the english specs for the Pessimism application.
 - [Telemetry](telemetry.markdown)
 
 ## GitHub Pages
-The Pessimism documentation is hosted on GitHub Pages. To view the documentation, please visit [https://base-org.github.io/pessimism](https://base-org.github.io/pessimism/architecture). 
-
+
+The Pessimism documentation is hosted on GitHub Pages. To view the documentation,
+please visit [https://base-org.github.io/pessimism](https://base-org.github.io/pessimism/architecture).
 
 ## Contributing
-If you would like to contribute to the Pessimism documentation, please advise the guidelines stipulated in the [CONTRIBUTING.md](../CONTRIBUTING.md) file __before__ submitting a pull request.
 
+If you would like to contribute to the Pessimism documentation, please advise
+the guidelines stipulated in the [CONTRIBUTING.md](../CONTRIBUTING.md)
+file __before__ submitting a pull request.
 
 ## Running Docs Website Locally
 
 ### Prerequisites
-- Ensure that you have installed the latest version of ruby on your machine following steps located [here](https://www.ruby-lang.org/en/documentation/installation/).
-- Installing ruby should also install the ruby bundler which is used to install dependencies located in the [Gemfile](Gemfile)
+
+- Ensure that you have installed the latest version of ruby on your machine
+following steps located [here](https://www.ruby-lang.org/en/documentation/installation/).
+- Installing ruby should also install the ruby bundler which is used to
+install dependencies located in the [Gemfile](Gemfile)
 
 ### Local Testing
-To run the documentation website locally, ensure you have followed the prerequisite steps, then do the following
+
+To run the documentation website locally, ensure you have followed the prerequisite
+steps, then do the following
+
 1. Install dependencies via `bundle install`
 2. Run `bundle exec jekyll serve`
 3. You should now see a localhost version of documentation for the website!
 
 ## Creating Diagrams in GitHub Pages
 
-It is important to note that you cannot simply write a mermaid diagram as you normally would with markdown and expect the diagram to be properly rendered via GitHub pages. To enable proper GitHub pages rendering, follow the recommended steps below:
+It is important to note that you cannot simply write a mermaid diagram as you
+normally would with markdown and expect the diagram to be properly rendered
+via GitHub pages. To enable proper GitHub pages rendering, follow the
+recommended steps below:
+
 1. Implement your diagram in markdown using the ` ```mermaid\n` key
-2. Once done with implementing the diagram, ff you have not already, import the mermaid.js library via the following 
-    ```
+2. Once done with implementing the diagram, ff you have not already,
+import the mermaid.js library via the following
+
+    ```bash
    {% raw %}
     <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/mermaid.min.js"></script>
     {% endraw %}
    ```
-3. Delete the ` ```mermaid ` key and replace it with 
-   ```
+
+3. Delete the ` ```mermaid ` key and replace it with
+
+   ```bash
    {% raw %}
     <div class="mermaid">
         --- diagram implementation here ---
     </div> 
    {% endraw %}
-   
-4. Done! To make sure this renders correctly, you can run `bundle exec jekyll serve` to view your changes.
+
+4. Done! To make sure this renders correctly, you can run
+`bundle exec jekyll serve` to view your changes.

docs/alert-routing.md

@@ -6,25 +6,30 @@ permalink: /alert-routing
 
 
 ## Overview
-The alert routing feature enables users to define a number of alert destinations and then route alerts to those 
-destinations based on the alert's severity. For example, a user may want to send all alerts to Slack but only send high 
-severity alerts to PagerDuty.
 
+The alert routing feature enables users to define a number of alert destinations
+and then route alerts to those destinations based on the alert's severity.
+For example, a user may want to send all alerts to Slack but only send high
+severity alerts to PagerDuty.
 
 ## How it works
+
 Alerts are routed to destinations based on the severity of the given heuristic.
-When a heuristic is deployed, the user must specify the severity of the alert that the heuristic will produce.
-When the heuristic is run, the alert is routed to the configured destinations based on the severity of the alert.
-For example, if a heuristic is configured to produce a high severity alert, the alert will be routed to all configured
-destinations that support high severity alerts.
+When a heuristic is deployed, the user must specify the severity of the alert
+that the heuristic will produce. When the heuristic is run, the alert is routed
+to the configured destinations based on the severity of the alert. For example,
+if a heuristic is configured to produce a high severity alert, the alert will be
+routed to all configured destinations that support high severity alerts.
 
-Each severity level is configured independently for each alert destination. A user can add any number of alert
-configurations per severity.
+Each severity level is configured independently for each alert destination.
+A user can add any number of alert configurations per severity.
 
-Located in the root directory you'll find a file named `alerts-template.yaml`. This file contains a template for
-configuring alert routing. The template contains a few examples on how you might want to configure your alert routing.
+Located in the root directory you'll find a file named `alerts-template.yaml`.
+This file contains a template for configuring alert routing. The template contains
+a few examples on how you might want to configure your alert routing.
 
 ## Supported Alert Destinations
+
 Pessimism currently supports the following alert destinations:
 
 | Name      | Description                         |
@@ -33,6 +38,7 @@ Pessimism currently supports the following alert destinations:
 | pagerduty | Sends alerts to a PagerDuty service |
 
 ## Alert Severity
+
 Pessimism currently defines the following severities for alerts:
 
 | Severity | Description                                                                 |
@@ -41,10 +47,12 @@ Pessimism currently defines the following severities for alerts:
 | medium   | Alerts that could be hazardous, but may not be completely destructive       |
 | high     | Alerts that require immediate attention and could result in a loss of funds |
 
-
 ## PagerDuty Severity Mapping
-PagerDuty supports the following severities: `critical`, `error`, `warning`, and `info`.
-Pessimism maps the Pessimism severities to [PagerDuty severities](https://developer.pagerduty.com/docs/ZG9jOjExMDI5NTgx-send-an-alert-event) as follows ([ref](../internal/core/alert.go)):
+
+PagerDuty supports the following severities: `critical`, `error`, `warning`,
+and `info`. Pessimism maps the Pessimism severities to
+[PagerDuty severities](https://developer.pagerduty.com/docs/ZG9jOjExMDI5NTgx-send-an-alert-event)
+as follows ([ref](../internal/core/alert.go)):
 
 | Pessimism | PagerDuty |
 |-----------|-----------|