fix(docs): system parameters schema and cue definition

.vscode/settings.recommended.json

@@ -1,5 +1,5 @@
 {
-  // Recommended `settings.json` configuration
+  "$comment": "Recommended `settings.json` configuration",
   "editor.formatOnSave": true,
   "editor.codeActionsOnSave": {
     "source.organizeImports": true,
@@ -37,12 +37,20 @@
     "rust",
     "rust/c509-certificate",
     "rust/cardano-chain-follower",
+    "rust/catalyst-types",
     "rust/catalyst-voting",
+    "rust/immutable-ledger",
+    "rust/vote-tx-v1",
+    "rust/vote-tx-v2",
+    "rust/signed-doc",
     "rust/cbork",
     "rust/hermes-ipfs",
+    "rust/rbac-registration",
+    "rust/cardano-blockchain-types",
     "dart",
     "docs",
-    "general"
+    "general",
+    "deps"
   ],
   "conventionalCommits.gitmoji": false,
   "markdown.extension.toc.unorderedList.marker": "*",

docs/src/architecture/08_concepts/signed_doc/diagrams/all.dot

@@ -1,4 +1,4 @@
-digraph "None" {
+digraph "All" {
     rankdir="LR"
     graph [fontname="helvetica", fontsize="32", fontcolor="#29235c", bgcolor="white"];
     node [penwidth="0", margin="0", fontname="helvetica", fontsize="32", fontcolor="#29235c"];

specs/gen_docs/gen/doc_generator.py

@@ -170,7 +170,7 @@ def add_reference_links(self) -> None:
 
         actual_link_names = self._spec.link_names()
 
-        actual_links_used = {}
+        actual_links_used: dict[str, str] = {}
         for link_name in actual_link_names:
             esc_link_name = re.escape(link_name)
             link_name_regex = f"(^|\\s)({esc_link_name})(\\.|\\s|$)"
@@ -190,7 +190,7 @@ def add_reference_links(self) -> None:
         for link, actual in actual_links_used.items():
             self._filedata += f"\n[{link}]: {actual}"
 
-    def remove_tabs(self, tabstop: int = 4) -> str:
+    def remove_tabs(self, tabstop: int = 4) -> None:
         """Replace tabs in the input text with spaces so that the text aligns on tab stops.
 
         Args:
@@ -343,7 +343,7 @@ def file_name(self) -> str:
         """Return the files name."""
         return self._filename
 
-    def file_path(self, relative_doc: typing.Self | None = None) -> Path:
+    def file_path(self, relative_doc: "DocGenerator | None" = None) -> Path:
         """Return a path to the file."""
         if relative_doc is not None:
             relative_path = relative_doc.file_path().parent

specs/gen_docs/gen/doc_relationship_diagrams.py

@@ -51,7 +51,7 @@ def generate(self) -> bool:  # noqa: C901
         file_title = textwrap.fill(f"{file_id} Document Relationships", width=30)
 
         dot_file = DotFile(
-            self._document_name, file_title, depth=self._depth, title_size=150 if self._document_name is None else 50
+            file_id, file_title, depth=self._depth, title_size=150 if self._document_name is None else 50
         )
 
         all_dst_refs: list[str] = []
@@ -66,7 +66,7 @@ def generate(self) -> bool:  # noqa: C901
             doc_data = self._spec.get_document(doc)
 
             # Add content type explicitely to table.
-            doc_table.add_row(TableRow(name="content type", value=doc_data.headers["content type"].value))
+            doc_table.add_row(TableRow(name="content type", value=doc_data.content_type))
 
             # Add all used Metadata to table.
             for meta in self._spec.all_headers(HeaderType.METADATA):

specs/gen_docs/gen/graphviz_doc_diagram.py

@@ -71,6 +71,11 @@ class TableRow(BaseModel):
 
     model_config = ConfigDict(extra="forbid")
 
+    @classmethod
+    def default_list(cls) -> list["TableRow"]:
+        """Return a default list of this class."""
+        return []
+
     def generate(self, bgcolor: str) -> str:
         """Generate a single row of the table."""
         value = self.value
@@ -171,14 +176,15 @@ def from_doc_cluster(cls, cluster: DocCluster | None) -> "Cluster | None":
             return None
         return cls(name=cluster.name)
 
+    @property
     def label(self) -> str:
         """Transform the name into a label."""
         return "cluster_" + self.name.lower().replace(" ", "_").replace("-", "_")
 
     def start(self) -> str:
         """Start a new cluster."""
         return f"""
-subgraph {self.label()} {{
+subgraph {self.label} {{
     label = "{self.name}";
     color=blue
     penwidth=20
@@ -188,7 +194,7 @@ def end(self) -> str:
         """End the cluster."""
         return "}\n"
 
-    def __eq__(self, other: "Cluster") -> bool:
+    def __eq__(self, other: object) -> bool:
         """Eq."""
         if not isinstance(other, Cluster):
             # don't attempt to compare against unrelated types
@@ -203,7 +209,7 @@ class DotSignedDoc(BaseModel):
     title_port: str = Field(default="title")
     title_href: str | None = Field(default=None)
     theme: TableTheme = Field(default_factory=TableTheme)
-    rows: list[TableRow] = Field(default_factory=list)
+    rows: list[TableRow] = Field(default_factory=TableRow.default_list)
     cluster: Cluster | None = Field(default=None)
 
     model_config = ConfigDict(extra="forbid")
@@ -296,6 +302,11 @@ def is_cluster(self) -> bool:
         """Is the link to a cluster."""
         return isinstance(self.port, Cluster)
 
+    @property
+    def port_label(self) -> str | None:
+        """Get label of the port."""
+        return self.port.label if self.is_cluster else None  # type: ignore  # noqa: PGH003
+
     def __str__(self) -> str:
         """Str."""
         name = f'"{self.id}"'
@@ -305,7 +316,7 @@ def __str__(self) -> str:
                 name += f":{self.dir}"
         return name
 
-    def __eq__(self, other: "DotLinkEnd") -> bool:
+    def __eq__(self, other: object) -> bool:
         """Eq."""
         if not isinstance(other, DotLinkEnd):
             # don't attempt to compare against unrelated types
@@ -335,12 +346,10 @@ def model_post_init(self, context: typing.Any) -> None:  # noqa: ANN401
         super().model_post_init(context)
 
         # Add cluster parameters to the theme.
-        if self.src.is_cluster:
-            self.theme.ltail = self.src.port.label()
-        if self.dst.is_cluster:
-            self.theme.lhead = self.dst.port.label()
+        self.theme.ltail = self.src.port_label
+        self.theme.lhead = self.dst.port_label
 
-    def __eq__(self, other: "DotLink") -> bool:
+    def __eq__(self, other: object) -> bool:
         """Eq."""
         if not isinstance(other, DotLink):
             # don't attempt to compare against unrelated types
@@ -367,20 +376,20 @@ def __init__(self, file_id: str, title: str, depth: int = 0, title_size: int = 1
         self.title = title
         self.title_size = title_size
         self.rankdir = "LR"
-        self.graph = {
+        self.graph: dict[str, str | int] = {
             "fontname": DEFAULT_FONT_NAME,
             "fontsize": DEFAULT_FONT_SIZE,
             "fontcolor": DEFAULT_FONT_COLOR,
             "bgcolor": "white",
         }
-        self.node = {
+        self.node: dict[str, str | int] = {
             "penwidth": 0,
             "margin": 0,
             "fontname": DEFAULT_FONT_NAME,
             "fontsize": DEFAULT_FONT_SIZE,
             "fontcolor": DEFAULT_FONT_COLOR,
         }
-        self.edge = {
+        self.edge: dict[str, str | int] = {
             "fontname": DEFAULT_FONT_NAME,
             "fontsize": DEFAULT_FONT_SIZE,
             "fontcolor": "red",
@@ -401,7 +410,7 @@ def add_table(self, table: DotSignedDoc) -> None:
         cluster_name = None
         if table.cluster is not None:
             cluster_name = table.cluster.name
-        if cluster_name is not None and cluster_name not in self.clusters:
+        if cluster_name is not None and cluster_name not in self.clusters and table.cluster is not None:
             self.clusters[cluster_name] = table.cluster
         if cluster_name not in self.tables:
             self.tables[cluster_name] = {}
@@ -438,9 +447,9 @@ def clustered_tables(self) -> str:
     def __str__(self) -> str:
         """Generate the DOT file."""
 
-        def defaults(name: str, settings: dict) -> str:
+        def defaults(name: str, settings: dict[str, str | int]) -> str:
             """Expand the defaults."""
-            defaults = []
+            defaults: list[str] = []
             for default, value in settings.items():
                 defaults.append(f'{default}="{value}"')
             return f"{name} [{', '.join(defaults)}];"

specs/gen_docs/spec/document.py

@@ -20,6 +20,11 @@ class DocumentBusinessLogic(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
 
+def empty_string_list() -> list[str]:
+    """Get an empty string list."""
+    return []
+
+
 class Document(BaseModel):
     """Document Data Definition."""
 
@@ -38,8 +43,8 @@ class Document(BaseModel):
     versions: list[ChangeLogEntry]
 
     _name: str | None = PrivateAttr(default=None)
-    _all_refs: list[str] = PrivateAttr(default_factory=list)
-    _refed_by: list[str] = PrivateAttr(default_factory=list)
+    _all_refs: list[str] = PrivateAttr(default_factory=empty_string_list)
+    _refed_by: list[str] = PrivateAttr(default_factory=empty_string_list)
 
     doc_name: str | None = Field(default=None)  # Set when wwe get a document
 
@@ -74,11 +79,21 @@ def all_references(self) -> list[str]:
         return self._all_refs
 
     @property
-    def name(self) -> list[str]:
+    def name(self) -> str:
         """Get name of this document."""
-        return self._name
+        return self._name if self._name is not None else "Unknown"
 
     @property
     def all_docs_referencing(self) -> list[str]:
         """Get name of all documents which reference this document."""
         return self._refed_by
+
+    @property
+    def content_type(self) -> str | list[str]:
+        """Get document content type."""
+        content_type = self.headers.get("content type")
+        if content_type is not None:
+            content_type = content_type.value
+        if content_type is None:
+            content_type = "Undefined"
+        return content_type