Implement id parser (#12)

* Update docs and README.md

Signed-off-by: Federico Busetti <729029+febus982@users.noreply.github.com>

* Parse document id from file name

Signed-off-by: Federico Busetti <729029+febus982@users.noreply.github.com>

---------

Signed-off-by: Federico Busetti <729029+febus982@users.noreply.github.com>

README.md

@@ -14,6 +14,12 @@
 
 This is a macro plugin to generates summaries from a list of a ADR documents in a directory.
 
+The single ADR documents file names have to respect this format: `0000-my-decision-title.md`
+
+* start with 4 digits followed by the character `-`
+* the rest of the file name can contain only letters, numbers, dashes and underscores (`[A-Za-z0-9_-]` regex)
+* end with the `.md` extension
+
 Examples and documentation can be found [here](https://febus982.github.io/mkdocs-macros-adr-summary)
 
 The package should be stable enough for daily use. I'll release 1.0.0, and switch to semantic version,
@@ -64,6 +70,7 @@ The `documents` variable in the jinja template is a Sequence of `ADRDocument` mo
 @dataclass
 class ADRDocument:
     file_path: str
+    document_id: Optional[int] = None
     title: Optional[str] = None
     date: Optional[date] = None
     status: Optional[str] = None
@@ -100,8 +107,7 @@ There are some differences in what metadata is available when using different fo
 The supported ADR formats are:
 * `nygard` format, it is recommended to use [adr-tools](https://github.com/npryce/adr-tools) to manage the directory
 * `MADR` [version 3](https://github.com/adr/madr/blob/3.0.0/template/adr-template.md)
-
-Support for [MADR](https://adr.github.io/madr/) version 2 will be added in a future version.
+* `MADR` [version 2](https://github.com/adr/madr/blob/2.1.2/template/template.md)
 
 ## Commands for development
 

docs/index.md

@@ -15,6 +15,12 @@
 
 This is a macro plugin to generates summaries from a list of a ADR documents in a directory.
 
+The single ADR documents file names have to respect this format: `0000-my-decision-title.md`
+
+* start with 4 digits followed by the character `-`
+* the rest of the file name can contain only letters, numbers, dashes and underscores (`[A-Za-z0-9_-]` regex)
+* end with the `.md` extension
+
 Examples and documentation can be found [here](https://febus982.github.io/mkdocs-macros-adr-summary)
 
 The package should be stable enough for daily use. I'll release 1.0.0, and switch to semantic version,
@@ -71,6 +77,7 @@ The `documents` variable in the jinja template is a Sequence of `ADRDocument` mo
 @dataclass
 class ADRDocument:
     file_path: str
+    document_id: Optional[int] = None
     title: Optional[str] = None
     date: Optional[date] = None
     status: Optional[str] = None
@@ -107,8 +114,7 @@ There are some differences in what metadata is available when using different fo
 The supported ADR formats are:
 * `nygard` format, it is recommended to use [adr-tools](https://github.com/npryce/adr-tools) to manage the directory
 * `MADR` [version 3](https://github.com/adr/madr/blob/3.0.0/template/adr-template.md)
-
-Support for [MADR](https://adr.github.io/madr/) version 2 will be added in a future version.
+* `MADR` [version 2](https://github.com/adr/madr/blob/2.1.2/template/template.md)
 
 ## Commands for development
 

mkdocs_macros_adr_summary/parser/base.py

@@ -52,7 +52,7 @@ def parse(cls, file_path: Path, base_path: Path) -> ADRDocument:
 
         doc = ADRDocument(
             file_path=fix_url(str(file_path.relative_to(base_path))),
-            document_id=cls._get_id(metadata, ast),
+            document_id=cls._get_id(file_path),
             title=cls._get_title(metadata, ast),
             date=cls._get_date(metadata, ast),
             status=cls._get_status(metadata, ast),
@@ -113,8 +113,11 @@ def _get_status(cls, metadata: dict, ast: TYPE_AST) -> Optional[str]: ...
     def _get_metadata_and_ast(cls, file: str) -> Tuple[Dict[str, Any], TYPE_AST]: ...
 
     @classmethod
-    @abstractmethod
-    def _get_id(cls, metadata: dict, ast: TYPE_AST) -> Optional[int]: ...
+    def _get_id(cls, file_path: Path) -> Optional[int]:
+        try:
+            return int(file_path.parts[-1][0:4])
+        except ValueError:
+            return None
 
     @classmethod
     def _get_deciders(cls, metadata: dict, ast: TYPE_AST) -> Optional[str]:

mkdocs_macros_adr_summary/parser/madr2.py

@@ -95,7 +95,3 @@ def _get_status(cls, metadata: dict, ast: TYPE_AST) -> Optional[str]:
     @classmethod
     def _get_deciders(cls, metadata: dict, ast: TYPE_AST) -> Optional[str]:
         return metadata.get("deciders")
-
-    @classmethod
-    def _get_id(cls, metadata: dict, ast: TYPE_AST) -> Optional[int]:
-        return None

mkdocs_macros_adr_summary/parser/madr3.py

@@ -79,7 +79,3 @@ def _get_consulted(cls, metadata: dict, ast: TYPE_AST) -> Optional[str]:
     @classmethod
     def _get_informed(cls, metadata: dict, ast: TYPE_AST) -> Optional[str]:
         return metadata.get("informed")
-
-    @classmethod
-    def _get_id(cls, metadata: dict, ast: TYPE_AST) -> Optional[int]:
-        return None

mkdocs_macros_adr_summary/parser/nygard.py

@@ -85,7 +85,3 @@ def _get_statuses(cls, metadata: dict, ast: TYPE_AST) -> Sequence[str]:
     def _get_status(cls, metadata: dict, ast: TYPE_AST) -> Optional[str]:
         statuses = cls._get_statuses(metadata, ast)
         return statuses[-1] if statuses else None
-
-    @classmethod
-    def _get_id(cls, metadata: dict, ast: TYPE_AST) -> Optional[int]:
-        return None

tests/test_madr2_parser.py

@@ -11,8 +11,9 @@
     ["filename", "expected_metadata"],
     [
         (
-            "valid_with_metadata.md",
+            "0001-valid_with_metadata.md",
             {
+                "document_id": 1,
                 "status": "Accepted",
                 "statuses": tuple(["Accepted"]),
                 "date": datetime.fromisoformat("2024-01-24").date(),
@@ -22,8 +23,9 @@
             },
         ),
         (
-            "valid_without_metadata.md",
+            "valid_without_metadata_and_id.md",
             {
+                "document_id": None,
                 "status": None,
                 "statuses": tuple(),
                 "date": None,

tests/test_madr3_parser.py

@@ -11,8 +11,9 @@
     ["filename", "expected_metadata"],
     [
         (
-            "valid_with_metadata.md",
+            "0001-valid_with_metadata.md",
             {
+                "document_id": 1,
                 "status": "Accepted",
                 "statuses": tuple(["Accepted"]),
                 "date": datetime.fromisoformat("2024-01-20").date(),
@@ -22,8 +23,9 @@
             },
         ),
         (
-            "valid_without_metadata.md",
+            "valid_without_metadata_and_id.md",
             {
+                "document_id": None,
                 "status": None,
                 "statuses": tuple(),
                 "date": None,

tests/test_nygard_parser.py

@@ -1,20 +1,23 @@
 from datetime import datetime
 from pathlib import Path
+from typing import Optional
 
 import pytest
 
 from mkdocs_macros_adr_summary.parser import NygardParser
 
 
 @pytest.mark.parametrize(
-    ["filename", "expected_statuses"],
+    ["filename", "expected_id", "expected_statuses"],
     [
         (
-            "valid.md",
+            "0001-valid.md",
+            1,
             ("Accepted",),
         ),
         (
             "valid_multi_status.md",
+            None,
             (
                 "Accepted",
                 "Supercedes [1. Record architecture decisions]"
@@ -24,7 +27,10 @@
     ],
 )
 def test_parse_valid_document(
-    filename: str, expected_statuses: tuple, adr_document_factory
+    filename: str,
+    expected_statuses: tuple,
+    expected_id: Optional[int],
+    adr_document_factory,
 ) -> None:
     doc = NygardParser.parse(
         Path(__file__).parent.joinpath(f"adr_docs/nygard/{filename}"),
@@ -36,6 +42,7 @@ def test_parse_valid_document(
         date=datetime.fromisoformat("2024-01-20").date(),
         status=expected_statuses[-1],
         statuses=expected_statuses,
+        document_id=expected_id,
     )
     assert doc == doc2