(Docs): Add instructions on comment style (#970)

Follow-up to #969. Adds instructions on adding comments with ignores, as
requested by user.

.trunk/trunk.yaml

@@ -53,6 +53,8 @@ lint:
       paths:
         - "**/test_data" # required for golangci-lint, which runs on directories
         - "**/test_data/**"
+    - linters: [prettier]
+      paths: [linters/markdownlint/README.md]
   threshold:
     - linters: [trunk]
       level: high

linters/eslint/README.md

@@ -31,6 +31,16 @@ alert("foo");
 alert("foo");
 ```
 
+### With Comments
+
+```typescript
+// trunk-ignore(eslint): Expected alert
+alert("foo");
+
+/* eslint-disable-next-line -- Expected alert */
+alert("foo");
+```
+
 ### Specific Issue
 
 ```typescript

linters/markdownlint/README.md

@@ -18,35 +18,39 @@ and [trunk-ignores](https://docs.trunk.io/code-quality/linters/ignoring-issues-a
 
 ```markdown
 <!-- trunk-ignore(markdownlint) -->
-
 # (name)[link]
 
 <!-- markdownlint-disable-next-line -->
+# (name)[link]
+```
+
+### With Comments
+
+```markdown
+<!-- trunk-ignore(markdownlint): Intentional -->
+# (name)[link]
 
+<!-- Unsupported in markdownlint -->
 # (name)[link]
 ```
 
 ### Specific Issue
 
 ```markdown
 <!-- trunk-ignore(markdownlint/MD011) -->
-
 # (name)[link]
 
 <!-- markdownlint-disable-next-line MD011 -->
-
 # (name)[link]
 ```
 
 ### Multiple Issues
 
 ```markdown
 <!-- trunk-ignore(markdownlint/MD001,markdownlint/MD011) -->
-
 # (name)[link]
 
 <!-- markdownlint-disable-next-line MD001 MD011 -->
-
 # (name)[link]
 ```
 
@@ -80,5 +84,8 @@ and [trunk-ignores](https://docs.trunk.io/code-quality/linters/ignoring-issues-a
 
 ### Notes
 
+By default, prettier will add empty lines between markdown content and comments.
+For this reason, we recommend using next-line ignores with [prettier ignores](https://prettier.io/docs/ignore/#range-ignore) or using ignore bocks.
+
 Specific rules and multi-file ignores can be specified in a
 [markdownlint config file](https://github.com/DavidAnson/markdownlint#optionsconfig).

linters/mypy/README.md

@@ -24,6 +24,14 @@ x: str = 1
 x: str = 1
 ```
 
+### With Comments
+
+```python
+x: str = 1  # trunk-ignore(mypy): Expected type
+
+x: str = 1  # Unsupported in mypy
+```
+
 ### Specific Issue
 
 ```python

linters/ruff/README.md

@@ -24,6 +24,14 @@ x = 1
 x = 1
 ```
 
+### With Comments
+
+```python
+x = 1  # trunk-ignore(ruff): Expected var
+
+x = 1  # noqa Expected var
+```
+
 ### Specific Issue
 
 ```python

tests/parse/index.ts

@@ -17,6 +17,7 @@ const RESULTS_FILE = path.resolve(REPO_ROOT, "results.json");
 const FAILURES_FILE = path.resolve(REPO_ROOT, "failures.yaml");
 const RERUN_FILE = path.resolve(REPO_ROOT, "reruns.txt");
 
+const EXCLUDED_RERUN_LINTERS: string[] = ["snyk"];
 const VALIDATED_LINTER_BLOCKLIST: string[] = [];
 
 const RUN_ID = process.env.RUN_ID ?? "";
@@ -357,12 +358,14 @@ const writeTestResults = (testResults: TestResultSummary) => {
         const allMetadata = Array.from(testFailureMetadata.values());
         // Must have at least one assertion_failure and no other failure types in order to proactively generate snapshot.
         const shouldRerunTest =
+          !EXCLUDED_RERUN_LINTERS.includes(linter) &&
           allMetadata.every(
             (failureMode) =>
               failureMode === "assertion_failure" ||
               failureMode === "skipped" ||
               failureMode === "passed",
-          ) && allMetadata.find((failureMode) => failureMode === "assertion_failure") !== undefined;
+          ) &&
+          allMetadata.find((failureMode) => failureMode === "assertion_failure") !== undefined;
         if (shouldRerunTest) {
           rerunPaths.push(testFilePath);
         }