Add markdownlint-cli2 CI check, clean up README, support rule IDs in --no-warn (#8)

koppor · claude · web-flow · commit e37d19b6699e · 2026-07-05T04:02:09.000+02:00
Co-authored-by: Claude Fable 5 &lt;noreply@anthropic.com&gt;
diff --git a/.github/workflows/markdownlint.yml b/.github/workflows/markdownlint.yml
@@ -0,0 +1,23 @@
+name: Markdown lint
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  markdownlint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Run markdownlint-cli2
+        uses: DavidAnson/markdownlint-cli2-action@v24
diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc
@@ -0,0 +1,13 @@
+{
+  "config": {
+    // Long lines are fine
+    "MD013": false,
+    "MD060": { "style": "aligned" }
+  },
+  "globs": ["**/*.md"],
+  "ignores": [
+    // Sample MADRs intentionally violate Markdown conventions
+    "madr-samples/**",
+    "**/build/**"
+  ]
+}
diff --git a/README.md b/README.md
@@ -1,20 +1,20 @@
 # madr-linter
 
 A Java-based linter for Markdown Architectural Decision Records (MADR).
-Learn more about MADR [here](https://www.ozimmer.ch/practices/2022/11/22/MADRTemplatePrimer.html).
+Learn more about MADR in the [MADR template primer](https://www.ozimmer.ch/practices/2022/11/22/MADRTemplatePrimer.html).
 
 ## Run with JBang
 
 With [JBang](https://www.jbang.dev/) installed (requires JRE 21 or newer), the
 linter can be run directly from this repository without cloning:
 
-```
+```shell
 jbang madrlint@adr/madrlint <madrFile>
 ```
 
 Or install it as a local command:
 
-```
+```shell
 jbang app install madrlint@adr/madrlint
 madrlint <madrFile>
 ```
@@ -24,17 +24,20 @@ madrlint <madrFile>
 1. Build and grab dependencies with: `.\gradlew build`
 2. Test the tool with: `.\gradlew run --args="[Options] <madrFile>"`
 
-**Arguments**
-```
+### Arguments
+
+```text
 <madrFile>                     Path to the Markdown Architectural Decision Record
                                (MADR) file to lint.
 ```
-**Options**
 
-```
+### Options
+
+```text
 -h, --help                     Show help message and exit.
 -V, --version                  Print version information and exit.
--n, --no-warn <disabledRules>  Disable warnings for certain rules. 
+-n, --no-warn <disabledRules>  Disable warnings for certain rules, given as rule
+                               number or rule ID (e.g -n1 or -nMADR01).
                                They can either be declared separately(e.g -n1 -n2) or 
                                chained together separated by comma(e.g -n1,2).            
 -o, --out <outputFile>         Output the diagnostics to a file. If that file does
@@ -46,50 +49,50 @@ madrlint <madrFile>
 -q, --quiet                    Information not relevant to the lint results will be
                                suppressed.
 ```
+
 ## Rules
 
+Violations are reported with a rule ID such as `MADR01a`: the rule number, optionally followed by a letter identifying the specific check within that rule.
+To disable a rule, pass its ID or number to `-n`/`--no-warn` (e.g., `-n MADR01` or `-n 1` disables all `MADR01` checks).
+
 ### Structural integrity
 
-```
-01. Mandatory sections: Title (a), Context and Problem Statement (b),
-    Considered Options (c), Decision Outcome (d) must be present.
-02. No sections may be empty.
-03. Chosen option must be mentioned first (b) inside Decision Outcome (a). Expected format: 'Chosen option: <chosen option>, because <rationale>'.
-04. Statement of chosen option must be followed by rationale in this format 'Chosen option: <chosen option>, because <rationale>'.
-05. Only the title is allowed to have heading level 1.
-06. Headings must have levels conforming to template's
-07. Consequences (a) and Confirmation (b), if present, must be H3 headings under Decision Outcome
-```
+| ID       | Description                                                                                                                                                                           |
+|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `MADR01` | The mandatory sections must be present: Title (`a`), Context and Problem Statement (`b`), Considered Options (`c`), and Decision Outcome (`d`).                                       |
+| `MADR02` | No section may be empty.                                                                                                                                                              |
+| `MADR03` | The chosen option must be stated inside Decision Outcome (`a`), and it must come first in that section (`b`). Expected format: `Chosen option: <chosen option>, because <rationale>`. |
+| `MADR04` | The statement of the chosen option must be followed by a rationale: `Chosen option: <chosen option>, because <rationale>`.                                                            |
+| `MADR05` | Only the title may have heading level 1.                                                                                                                                              |
+| `MADR06` | Headings must have the levels given in the MADR template.                                                                                                                             |
+| `MADR07` | Consequences (`a`) and Confirmation (`b`), if present, must be level-3 headings under Decision Outcome.                                                                               |
 
 ### Link validity
 
-```
-11. Internet links must be valid.
-12. Local links (Anchor links, local paths to resources, etc) must be valid.
-```
+| ID       | Description                                                               |
+|----------|---------------------------------------------------------------------------|
+| `MADR11` | Internet links must be valid.                                             |
+| `MADR12` | Local links (anchor links, local paths to resources, etc.) must be valid. |
 
 ### Syntactic validity
 
-```
-21. Metadata content must have proper syntax adhering to YAML rules.
-```
+| ID       | Description                                                      |
+|----------|------------------------------------------------------------------|
+| `MADR21` | Metadata content must have proper syntax adhering to YAML rules. |
 
 ### Stylistic neutrality
 
-```
-31. Asterisks (*) must be used as list markers.
-```
+| ID       | Description                                   |
+|----------|-----------------------------------------------|
+| `MADR31` | Asterisks (`*`) must be used as list markers. |
 
 ### Organizational soundness
 
-```
-41. The numberings of ADRs within the ADR directory must start with either 0000 or 
-0001 (a) and feature no skips (b).
-42. No 'foreign' files may be present inside ADR directory.
-43. No collisions of numberings between MADRs in the same folder.
-44. MADRs must follow the naming scheme: 'XXXX-brief-description.md'
-```
-The rules marked with * are rules for which checks are yet to be implemented.
-
-See [here](https://github.com/adr/madr/blob/develop/template/adr-template.md) for the MADR template on which the rules are based.
+| ID       | Description                                                                                                              |
+|----------|--------------------------------------------------------------------------------------------------------------------------|
+| `MADR41` | The numbering of ADRs within the ADR directory must start with either `0000` or `0001` (`a`) and feature no skips (`b`). |
+| `MADR42` | No 'foreign' files may be present inside the ADR directory.                                                              |
+| `MADR43` | Numberings must not collide between MADRs in the same folder.                                                            |
+| `MADR44` | MADRs must follow the naming scheme `NNNN-brief-description.md`.                                                         |
 
+The rules are based on the [MADR template](https://github.com/adr/madr/blob/develop/template/adr-template.md).
diff --git a/app/src/main/java/neutra1/linter/Main.java b/app/src/main/java/neutra1/linter/Main.java
@@ -41,7 +41,7 @@
     name = "madrlint",
     description = "Lint MADR files",
     mixinStandardHelpOptions = true,
-    customSynopsis = "madrlint [-hOqV] [-n <ruleNumber>[,ruleNumber...]>] [-o <outputFile>] [--output-format <format>] <madrFile>",
+    customSynopsis = "madrlint [-hOqV] [-n <rule>[,rule...]] [-o <outputFile>] [--output-format <format>] <madrFile>",
     version="1.0.0"
 )
 public class Main implements Runnable {
@@ -58,7 +58,7 @@ public class Main implements Runnable {
     private boolean override;
     @Option(names = {"-q", "--quiet"}, description = "Information not relevant to the lint results will be suppressed.")
     boolean quietMode;
-    @Option(names = {"-n", "--no-warn"}, description = "Disable warnings for certain rules. They can either be declared separately(e.g -n1 -n2) or chained together separated by comma(e.g -n1,2)", split = ",")
+    @Option(names = {"-n", "--no-warn"}, description = "Disable warnings for certain rules, given as rule number or rule ID (e.g -n1 or -nMADR01). They can either be declared separately(e.g -n1 -n2) or chained together separated by comma(e.g -n1,2)", split = ",", converter = RuleIdConverter.class)
     private Set<Integer> disabledRules = new HashSet<>();
     @Option(names = {"--output-format"}, description = "Format of the diagnostics. Valid values: errorformat, github-actions. Defaults to errorformat.", converter = OutputFormatConverter.class)
     private OutputFormat outputFormat = OutputFormat.ERRORFORMAT;
@@ -135,6 +135,19 @@ public static void main(String[] args) {
         System.exit(exitCode);
     }
 
+    static class RuleIdConverter implements CommandLine.ITypeConverter<Integer> {
+        @Override
+        public Integer convert(String value) {
+            String number = value.toUpperCase().startsWith("MADR") ? value.substring(4) : value;
+            try {
+                return Integer.parseInt(number);
+            }
+            catch (NumberFormatException e){
+                throw new CommandLine.TypeConversionException("Invalid rule '" + value + "'. Expected a rule number (e.g. 1) or a rule ID (e.g. MADR01).");
+            }
+        }
+    }
+
     static class OutputFormatConverter implements CommandLine.ITypeConverter<OutputFormat> {
         @Override
         public OutputFormat convert(String value) {
