deriva-cli 0.8.2__tar.gz → 0.8.4__tar.gz

{deriva_cli-0.8.2 → deriva_cli-0.8.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deriva-cli
-Version: 0.8.2
+Version: 0.8.4
 Summary: Deriva is a research project aimed at enabling digital architects by automating the derivation of enterprise architecture models. Deriva uses dual knowledge graphs, heuristics and LLM's.
 Keywords: archimate,enterprise-architecture,code-analysis,llm,grafeo,fastapi
 Author: S. T. Grond
@@ -38,8 +38,8 @@ Requires-Dist: spacy==3.8.16
 Requires-Dist: ctranslate2==4.8.3
 Requires-Dist: sentencepiece==0.2.2
 Requires-Dist: solvor>=0.6.3
-Requires-Dist: pydantic-ai-slim[openai,anthropic]>=2.55
-Requires-Dist: httpx2>=2.13
+Requires-Dist: pydantic-ai-slim[openai,anthropic]>=2.57
+Requires-Dist: httpx2>=2.14
 Requires-Dist: lmdb>=1.6
 Requires-Dist: typer>=0.27
 Requires-Dist: tree-sitter-typescript==0.23.2

{deriva_cli-0.8.2 → deriva_cli-0.8.4}/deriva/adapters/archimate/manager.py

@@ -577,6 +577,35 @@ class ArchimateManager:
             key=lambda e: str(e["identifier"]),
         )
 
+    def update_element_properties(self, updates: dict[str, dict[str, Any]]) -> int:
+        """Merge keys into the properties of elements (identifier -> keys), leaving their other keys; returns how many changed."""
+        if self.db is None:
+            raise RuntimeError("Not connected to grafeo. Call connect() first.")
+        changed = 0
+        for identifier, keys in sorted(updates.items()):
+            rows = self.db.execute(f"MATCH (e:`{self.namespace}` {{identifier: $identifier}}) RETURN e.properties AS properties", {"identifier": identifier})
+            if not rows:
+                continue
+            merged = {**(rows[0].get("properties") or {}), **keys}
+            self.db.execute_write(f"MATCH (e:`{self.namespace}` {{identifier: $identifier}}) SET e.properties = $properties", {"identifier": identifier, "properties": merged})
+            changed += 1
+        return changed
+
+    def update_relationship_properties(self, updates: dict[str, dict[str, Any]]) -> int:
+        """Merge keys into the properties of relationships (identifier -> keys), in place; returns how many changed."""
+        if self.db is None:
+            raise RuntimeError("Not connected to grafeo. Call connect() first.")
+        changed = 0
+        for identifier, keys in sorted(updates.items()):
+            match = f"MATCH (:`{self.namespace}`)-[r {{identifier: $identifier}}]->(:`{self.namespace}`)"
+            rows = self.db.execute(f"{match} RETURN r.properties AS properties", {"identifier": identifier})
+            if not rows:
+                continue
+            merged = {**(rows[0].get("properties") or {}), **keys}
+            self.db.execute_write(f"{match} SET r.properties = $properties", {"identifier": identifier, "properties": merged})
+            changed += 1
+        return changed
+
     def delete_relationship(self, identifier: str) -> bool:
         """Delete a relationship by identifier.
 

{deriva_cli-0.8.2 → deriva_cli-0.8.4}/deriva/adapters/archimate/views.py

@@ -1,7 +1,8 @@
 """Generated views (pure): ArchiMate viewpoints per level with a deterministic band layout.
 
-Each viewpoint (ArchiMate 3.2 Specification, chapter 13) shows the architect elements of its types; a detail
-variant adds the detail elements (property ``level`` = detail) nested under those types. The layout puts the
+Each viewpoint (ArchiMate 3.2 Specification, chapter 13) shows the elements of its types on its level (enterprise or
+solution, from the element's ``levels``) and the relationships on that level; a cross-level link is in no view. A
+detail variant shows the solution elements of its types with their detail elements (property ``level`` = detail). The layout puts the
 layers in horizontal bands (business, application, technology) and the elements of a band in a grid, ordered by
 type and name, each detail element right after its parent, so the same model gives the same view in every run.
 """
@@ -12,23 +13,32 @@ from dataclasses import dataclass, field
 
 from .models import Element, Relationship, layer_of
 
-# (view name, viewpoint, element types, with detail elements)
-VIEWPOINTS: tuple[tuple[str, str, frozenset[str] | None, bool], ...] = (
-    ("Layered", "Layered", None, False),
-    ("Application Cooperation", "Application Cooperation", frozenset({"ApplicationComponent", "ApplicationInterface", "ApplicationService"}), False),
-    ("Information Structure", "Information Structure", frozenset({"BusinessObject", "DataObject"}), False),
-    ("Information Structure (detail)", "Information Structure", frozenset({"BusinessObject", "DataObject"}), True),
-    ("Implementation and Deployment", "Implementation and Deployment", frozenset({"ApplicationComponent", "Node", "Device", "SystemSoftware", "TechnologyService"}), False),
+ENTERPRISE, SOLUTION, DETAIL = "enterprise", "solution", "detail"
+DEPLOYMENT = frozenset({"ApplicationComponent", "Node", "Device", "SystemSoftware", "TechnologyService"})
+# (view name, viewpoint, element types, level), in export order
+VIEWPOINTS: tuple[tuple[str, str, frozenset[str] | None, str], ...] = (
+    ("Layered (enterprise)", "Layered", None, ENTERPRISE),
+    ("Application Cooperation (enterprise)", "Application Cooperation", frozenset({"ApplicationComponent", "ApplicationInterface", "ApplicationService"}), ENTERPRISE),
+    ("Information Structure (enterprise)", "Information Structure", frozenset({"BusinessObject", "DataObject"}), ENTERPRISE),
+    ("Implementation and Deployment (enterprise)", "Implementation and Deployment", DEPLOYMENT, ENTERPRISE),
     (
-        "Implementation and Deployment (detail)",
-        "Implementation and Deployment",
-        frozenset({"ApplicationComponent", "Node", "Device", "SystemSoftware", "TechnologyService", "Artifact"}),
-        True,
+        "Business (enterprise)",
+        "Business Process Cooperation",
+        frozenset({"BusinessActor", "BusinessProcess", "BusinessFunction", "BusinessEvent", "ApplicationService"}),
+        ENTERPRISE,
     ),
-    ("Business", "Business Process Cooperation", frozenset({"BusinessActor", "BusinessProcess", "BusinessFunction", "BusinessEvent", "ApplicationService"}), False),
+    ("Application Structure (solution)", "Application Structure", frozenset({"ApplicationComponent"}), SOLUTION),
+    ("Application Cooperation (solution)", "Application Cooperation", frozenset({"ApplicationComponent", "ApplicationInterface"}), SOLUTION),
+    ("Information Structure (solution)", "Information Structure", frozenset({"DataObject"}), SOLUTION),
+    ("Implementation and Deployment (solution)", "Implementation and Deployment", DEPLOYMENT, SOLUTION),
+    ("Information Structure (detail)", "Information Structure", frozenset({"DataObject"}), DETAIL),
+    ("Implementation and Deployment (detail)", "Implementation and Deployment", DEPLOYMENT | {"Artifact"}, DETAIL),
+    # The interfaces with their members (endpoints, pages, jobs); components are left out, their members are above
+    ("Application Interfaces (detail)", "Application Cooperation", frozenset({"ApplicationInterface"}), DETAIL),
 )
+
 # A view needs an element of its anchor types (the Business view: a business element, not application services alone)
-ANCHORS = {"Business": frozenset({"BusinessActor", "BusinessProcess", "BusinessFunction", "BusinessEvent"})}
+ANCHORS = {"Business (enterprise)": frozenset({"BusinessActor", "BusinessProcess", "BusinessFunction", "BusinessEvent"})}
 BANDS = ("Business", "Application", "Technology", "Other")
 TYPE_ORDER = (
     "BusinessActor", "BusinessFunction", "BusinessProcess", "BusinessEvent", "BusinessObject",
@@ -61,7 +71,7 @@ class View:
     identifier: str
     name: str
     viewpoint: str
-    level: str = "architect"  # detail: the view shows the detail elements too
+    level: str = ENTERPRISE  # enterprise, solution or detail (a detail view shows the detail elements too)
     nodes: list[ViewNode] = field(default_factory=list)
     connections: list[ViewConnection] = field(default_factory=list)
 
@@ -70,6 +80,23 @@ def _level(e: Element) -> str:
     return str((e.properties or {}).get("level") or "architect")
 
 
+def _levels(properties: dict | None) -> frozenset[str]:
+    """The levels of an element or relationship: ``level`` detail, else ``levels`` (empty: a cross-level link), else the
+    enterprise level (a model from before the levels)."""
+    properties = properties or {}
+    if properties.get("level") == DETAIL:
+        return frozenset({DETAIL})
+    levels = properties.get("levels")
+    if isinstance(levels, list):
+        return frozenset(str(v) for v in levels)
+    return frozenset() if properties.get("cross_level") else frozenset({ENTERPRISE})
+
+
+def _on(level: str, levels: frozenset[str]) -> bool:
+    """Whether something on ``levels`` belongs in a view of ``level`` (a detail view: the solution level and the detail)."""
+    return bool(levels & ({SOLUTION, DETAIL} if level == DETAIL else {level}))
+
+
 def _order(e: Element) -> tuple[int, str, str]:
     return (TYPE_ORDER.index(e.element_type) if e.element_type in TYPE_ORDER else len(TYPE_ORDER), e.name.casefold(), e.identifier)
 
@@ -102,19 +129,25 @@ def _layout(view: View, shown: list[Element]) -> None:
         y += BAND_GAP
 
 
-def build_views(elements: list[Element], relationships: list[Relationship]) -> list[View]:
-    """The views of the model, one per viewpoint that has elements, in VIEWPOINTS order."""
+def build_views(elements: list[Element], relationships: list[Relationship], relationship_levels: dict[str, frozenset[str]] | None = None) -> list[View]:
+    """The views of the model, one per viewpoint that has elements on its level, in VIEWPOINTS order.
+
+    Args:
+        relationship_levels: Relationship id -> its levels, where the relationship's own properties do not say (the
+            export's detail relationships); else from the properties
+    """
     views: list[View] = []
-    for number, (name, viewpoint, types, with_detail) in enumerate(VIEWPOINTS, 1):
-        shown = [e for e in elements if (types is None or e.element_type in types) and (with_detail or _level(e) != "detail")]
+    for number, (name, viewpoint, types, level) in enumerate(VIEWPOINTS, 1):
+        shown = [e for e in elements if (types is None or e.element_type in types) and _on(level, _levels(e.properties))]
         anchors = ANCHORS.get(name)
-        if not shown or (anchors and not any(e.element_type in anchors for e in shown)) or (with_detail and not any(_level(e) == "detail" for e in shown)):
+        if not shown or (anchors and not any(e.element_type in anchors for e in shown)) or (level == DETAIL and not any(_level(e) == DETAIL for e in shown)):
             continue
-        view = View(identifier=f"view-{number}", name=name, viewpoint=viewpoint, level="detail" if with_detail else "architect")
+        view = View(identifier=f"view-{number}", name=name, viewpoint=viewpoint, level=level)
         _layout(view, shown)
         node_of = {n.element: n.identifier for n in view.nodes}
         for r in sorted(relationships, key=lambda r: r.identifier):
-            if r.source in node_of and r.target in node_of:
+            on = (relationship_levels or {}).get(r.identifier) or _levels(r.properties)
+            if r.source in node_of and r.target in node_of and _on(level, on):
                 connection = ViewConnection(identifier=f"{view.identifier}-c-{r.identifier}", relationship=r.identifier, source=node_of[r.source], target=node_of[r.target])
                 view.connections.append(connection)
         views.append(view)

{deriva_cli-0.8.2 → deriva_cli-0.8.4}/deriva/adapters/archimate/xml_export.py

@@ -51,6 +51,7 @@ class ArchiMateXMLExporter:
         model_id: str = "model-001",
         properties: Mapping[str, Mapping[str, str]] | None = None,
         views: Sequence[View] | None = None,
+        relationship_properties: Mapping[str, Mapping[str, str]] | None = None,
     ) -> None:
         """
         Export ArchiMate model to XML file.
@@ -63,6 +64,7 @@ class ArchiMateXMLExporter:
             model_id: Unique identifier for the model
             properties: Exported properties per element id (e.g. ``level``), declared as propertyDefinitions
             views: Diagrams to export (see ``views.build_views``)
+            relationship_properties: Exported properties per relationship id, declared with the element ones
         """
         # Create root model element
         root = etree.Element(
@@ -83,7 +85,8 @@ class ArchiMateXMLExporter:
         self._add_metadata(root)
 
         properties = properties or {}
-        keys = sorted({key for values in properties.values() for key, value in values.items() if value})
+        relationship_properties = relationship_properties or {}
+        keys = sorted({key for values in [*properties.values(), *relationship_properties.values()] for key, value in values.items() if value})
         definition_of = {key: f"propid-{key}" for key in keys}
 
         # Add elements section
@@ -96,7 +99,7 @@ class ArchiMateXMLExporter:
         if relationships:
             rels_section = etree.SubElement(root, "relationships")
             for relationship in relationships:
-                self._add_relationship(rels_section, relationship)
+                self._add_relationship(rels_section, relationship, relationship_properties.get(relationship.identifier, {}), definition_of)
 
         # The exchange format's order: elements, relationships, organizations, propertyDefinitions, views
         if keys:
@@ -105,7 +108,7 @@ class ArchiMateXMLExporter:
                 definition = etree.SubElement(definitions, "propertyDefinition", attrib={"identifier": definition_of[key], "type": "string"})
                 etree.SubElement(definition, "name").text = key
         if views:
-            self._add_views(root, views)
+            self._add_views(root, views, definition_of.get("level"))
 
         # Write to file
         tree = etree.ElementTree(root)
@@ -190,8 +193,9 @@ class ArchiMateXMLExporter:
                 value_elem.set(f"{{{self.XML_NS}}}lang", "en")
                 value_elem.text = value
 
-    def _add_views(self, root: etree.Element, views: Sequence[View]) -> None:
-        """Add the diagrams: element nodes with their bounds, relationship connections between them."""
+    def _add_views(self, root: etree.Element, views: Sequence[View], level_definition: str | None = None) -> None:
+        """Add the diagrams: element nodes with their bounds, relationship connections between them, and each view's
+        level as a property where the model declares one."""
         diagrams = etree.SubElement(etree.SubElement(root, "views"), "diagrams")
         for view in views:
             diagram = etree.SubElement(
@@ -202,6 +206,11 @@ class ArchiMateXMLExporter:
             name_elem = etree.SubElement(diagram, "name")
             name_elem.set(f"{{{self.XML_NS}}}lang", "en")
             name_elem.text = view.name
+            if level_definition:
+                prop = etree.SubElement(etree.SubElement(diagram, "properties"), "property", attrib={"propertyDefinitionRef": level_definition})
+                value_elem = etree.SubElement(prop, "value")
+                value_elem.set(f"{{{self.XML_NS}}}lang", "en")
+                value_elem.text = view.level
             for node in view.nodes:
                 etree.SubElement(
                     diagram,
@@ -229,13 +238,21 @@ class ArchiMateXMLExporter:
                     },
                 )
 
-    def _add_relationship(self, parent: etree.Element, relationship: Relationship) -> None:
+    def _add_relationship(
+        self,
+        parent: etree.Element,
+        relationship: Relationship,
+        properties: Mapping[str, str] | None = None,
+        definition_of: Mapping[str, str] | None = None,
+    ) -> None:
         """
         Add a relationship to the XML tree.
 
         Args:
             parent: Parent XML element
             relationship: ArchiMate relationship to add
+            properties: The relationship's exported properties (key -> value)
+            definition_of: propertyDefinition identifier per key
         """
         rel = etree.SubElement(
             parent,
@@ -258,8 +275,15 @@ class ArchiMateXMLExporter:
             doc_elem = etree.SubElement(rel, "documentation")
             doc_elem.text = relationship.documentation
 
-        # Note: Properties are not exported as they require propertyDefinitions
-        # at the model level per ArchiMate Exchange Format XSD.
+        # Only the properties passed in are exported (each needs a model-level propertyDefinition), after name and documentation
+        shown = sorted((key, value) for key, value in (properties or {}).items() if value and key in (definition_of or {}))
+        if shown and definition_of:
+            props = etree.SubElement(rel, "properties")
+            for key, value in shown:
+                prop = etree.SubElement(props, "property", attrib={"propertyDefinitionRef": definition_of[key]})
+                value_elem = etree.SubElement(prop, "value")
+                value_elem.set(f"{{{self.XML_NS}}}lang", "en")
+                value_elem.text = str(value)
 
     def export_to_string(
         self,

{deriva_cli-0.8.2 → deriva_cli-0.8.4}/deriva/adapters/database/__init__.py

@@ -30,6 +30,7 @@ from .db_tool import export_all as export_database
 from .db_tool import import_all as import_database
 from .manager import (
     DB_PATH,
+    ConfigDatabaseBusy,
     ensure_database,
     get_connection,
     init_database,
@@ -43,6 +44,7 @@ FUNCTION_MODELS_DIR = DATA_DIR / "function_models"
 
 __all__ = [
     "FUNCTION_MODELS_DIR",
+    "ConfigDatabaseBusy",
     "ensure_database",
     "get_connection",
     "init_database",

{deriva_cli-0.8.2 → deriva_cli-0.8.4}/deriva/adapters/database/manager.py

@@ -28,6 +28,14 @@ SCRIPTS_DIR = Path(__file__).parent / "scripts"
 DATA_DIR = Path(__file__).parent / "data"
 
 
+# How DuckDB reports a database file another process holds (Windows; Linux and macOS)
+_LOCK_MESSAGES = ("being used by another process", "Could not set lock", "Conflicting lock")
+
+
+class ConfigDatabaseBusy(RuntimeError):
+    """The config database is open in another process (DuckDB allows one writer)."""
+
+
 def get_connection(read_only: bool = False) -> duckdb.DuckDBPyConnection:
     """Get a connection to the database.
 
@@ -37,11 +45,21 @@ def get_connection(read_only: bool = False) -> duckdb.DuckDBPyConnection:
 
     Returns:
         DuckDB connection
+
+    Raises:
+        ConfigDatabaseBusy: Another process (the studio, another CLI run) holds the database
     """
     # A fresh install has no database yet: create it from the schema and the shipped seed data
     if not DB_PATH.exists():
         ensure_database(DB_PATH)
-    return duckdb.connect(str(DB_PATH), read_only=read_only)
+    try:
+        return duckdb.connect(str(DB_PATH), read_only=read_only)
+    except duckdb.IOException as e:
+        if any(message in str(e) for message in _LOCK_MESSAGES):
+            raise ConfigDatabaseBusy(
+                f"The config database {DB_PATH} is open in another Deriva process (the studio or another deriva-cli run). Close it, or wait for it to finish, then try again."
+            ) from e
+        raise
 
 
 def run_sql_file(filepath: Path, conn: duckdb.DuckDBPyConnection | None = None) -> int:

{deriva_cli-0.8.2 → deriva_cli-0.8.4}/deriva/adapters/grafeo/__init__.py

@@ -21,9 +21,13 @@ from .manager import (
     DEFAULT_DATABASE,
     GrafeoConnection,
     close_database,
+    database_bytes,
+    database_exists,
     database_file,
+    delete_database,
     engine_info,
     get_database,
+    list_databases,
     use_database,
 )
 
@@ -31,8 +35,12 @@ __all__ = [
     "DEFAULT_DATABASE",
     "GrafeoConnection",
     "close_database",
+    "database_bytes",
+    "database_exists",
     "database_file",
+    "delete_database",
     "engine_info",
     "get_database",
+    "list_databases",
     "use_database",
 ]

{deriva_cli-0.8.2 → deriva_cli-0.8.4}/deriva/adapters/grafeo/manager.py

@@ -27,8 +27,10 @@ Usage:
 from __future__ import annotations
 
 import logging
+import shutil
 import time
 import weakref
+from pathlib import Path
 from typing import Any
 
 from deriva.common.paths import resolve
@@ -77,6 +79,55 @@ def database_file(key: str) -> str | None:
     return str(folder / f"{key}.grafeo")
 
 
+def _stored_paths(key: str) -> tuple[Path, Path] | None:
+    """The key's database file and its write-ahead log folder, never created (None in memory or for an invalid key)."""
+    directory = GrafeoSettings().db_dir
+    if not directory or not key or key in (".", "..") or any(sep in key for sep in ("/", "\\")):
+        return None
+    folder = resolve(directory)
+    return folder / f"{key}.grafeo", folder / f"{key}.grafeo.wal"
+
+
+def database_exists(key: str) -> bool:
+    """Whether the key's database file exists; never creates it or its folder (False in memory or for an invalid key)."""
+    paths = _stored_paths(key)
+    return paths is not None and paths[0].exists()
+
+
+def list_databases() -> list[str]:
+    """The keys with a database file in GRAFEO_DB_DIR, sorted (none in memory)."""
+    directory = GrafeoSettings().db_dir
+    folder = resolve(directory) if directory else None
+    if folder is None or not folder.is_dir():
+        return []
+    return sorted(path.name.removesuffix(".grafeo") for path in folder.glob("*.grafeo") if path.is_file())
+
+
+def database_bytes(key: str) -> int:
+    """Bytes the key's database takes on disk: its file and its write-ahead log (0 when it has none)."""
+    paths = _stored_paths(key)
+    if paths is None:
+        return 0
+    database, log = paths
+    size = database.stat().st_size if database.is_file() else 0
+    return size + (sum(f.stat().st_size for f in log.rglob("*") if f.is_file()) if log.is_dir() else 0)
+
+
+def delete_database(key: str) -> bool:
+    """Delete the key's database file and log; False when it had none. The active database is never deleted (switch
+    away first): a query after the delete would create a new, empty file."""
+    if key == _db_key:
+        raise ValueError(f"The database {key!r} is open; switch to another one before deleting it")
+    paths = _stored_paths(key)
+    if paths is None or not (paths[0].exists() or paths[1].exists()):
+        return False
+    database, log = paths
+    database.unlink(missing_ok=True)
+    if log.is_dir():
+        shutil.rmtree(log)
+    return True
+
+
 def get_database() -> Any:
     """Get or open the active GrafeoDB instance (see ``use_database``).
 

{deriva_cli-0.8.2 → deriva_cli-0.8.4}/deriva/adapters/graph/manager.py

@@ -26,7 +26,7 @@ from __future__ import annotations
 
 import logging
 import re
-from collections.abc import Iterator
+from collections.abc import Generator
 from contextlib import contextmanager
 from dataclasses import dataclass, field
 from typing import Any
@@ -36,6 +36,7 @@ from deriva.common.ocel import create_edge_id
 from deriva.common.settings import GraphSettings
 
 from .models import (
+    BuildModuleNode,
     BusinessConceptNode,
     DataDomainNode,
     DataEntityNode,
@@ -72,6 +73,7 @@ GraphNode = (
     | ServiceNode
     | ExternalDependencyNode
     | DeployableUnitNode
+    | BuildModuleNode
     | DataEntityNode
     | DataDomainNode
     | EnvironmentNode
@@ -278,7 +280,7 @@ class GraphManager:
             raise
 
     @contextmanager
-    def step_tags(self, step: str, version: int | None = None) -> Iterator[None]:
+    def step_tags(self, step: str, version: int | None = None) -> Generator[None]:
         """Nodes and edges written inside the block carry the extraction step (``extractStep``) and its version."""
         previous = self._step_tags
         self._step_tags = {"extractStep": step, **({"extractVersion": version} if version is not None else {})}
@@ -288,7 +290,7 @@ class GraphManager:
             self._step_tags = previous
 
     @contextmanager
-    def recording(self) -> Iterator[GraphWrites]:
+    def recording(self) -> Generator[GraphWrites]:
         """The nodes and edges written inside the block (for the run log); failed writes are left out."""
         recorder = GraphWrites()
         self._recorders.append(recorder)

{deriva_cli-0.8.2 → deriva_cli-0.8.4}/deriva/adapters/graph/metamodel.py

@@ -13,6 +13,10 @@ from typing import Any
 from . import models
 
 __all__ = [
+    "GROUP_ORDER",
+    "NODE_GROUPS",
+    "node_description",
+    "node_group",
     "get_all_node_classes",
     "get_node_properties",
     "get_relationship_types",
@@ -36,7 +40,45 @@ def get_all_node_classes() -> dict[str, type]:
     return node_classes
 
 
-def get_node_properties(node_class: type) -> list[str]:
+# The intermediate ontology's groups (as ArchiMate has its layers): where a node type's evidence comes from
+GROUP_ORDER = ("structure", "code", "business", "deployment")
+NODE_GROUPS = {
+    "Repository": "structure",
+    "Directory": "structure",
+    "File": "structure",
+    "Module": "structure",
+    "BuildModule": "structure",
+    "TypeDefinition": "code",
+    "Method": "code",
+    "Test": "code",
+    "ExternalDependency": "code",
+    "Service": "code",
+    "BusinessConcept": "business",
+    "DataEntity": "business",
+    "DataDomain": "business",
+    "Lifecycle": "business",
+    "LifecycleEvent": "business",
+    "Role": "business",
+    "DeployableUnit": "deployment",
+    "Deployment": "deployment",
+    "Environment": "deployment",
+    "Software": "deployment",
+    "Technology": "deployment",
+}
+
+
+def node_group(node_type: str) -> str:
+    """The group of a node type (``other`` for a label the metamodel does not name)."""
+    return NODE_GROUPS.get(node_type, "other")
+
+
+def node_description(node_class: type) -> str:
+    """The first line of a node class's docstring."""
+    lines = (node_class.__doc__ or "").strip().splitlines()
+    return lines[0].strip() if lines else ""
+
+
+def get_node_properties(node_class: type[Any]) -> list[str]:
     """Get all property names for a node class.
 
     Args:

{deriva_cli-0.8.2 → deriva_cli-0.8.4}/deriva/adapters/graph/models.py

@@ -506,6 +506,45 @@ class ExternalDependencyNode:
         }
 
 
+@dataclass
+class BuildModuleNode:
+    """A build module (a folder with a build manifest and code of its own) or a parent system (an aggregator manifest
+    that lists modules). Its own files hang below it by ``INCLUDES``, nested modules by ``NESTS``; a deployable unit
+    ``BUILDS`` the modules in its folder."""
+
+    name: str
+    path: str
+    manifest: str
+    repository_name: str
+    is_module: bool = False
+    is_system: bool = False
+    members: list[str] = field(default_factory=list)  # For a system: the module paths its manifest lists
+    same_as: str | None = None  # The unit whose folder it is (one unit there, no module inside): one element with it
+    excluded: str | None = None  # Why it is no application component (infrastructure-as-code, test-only)
+
+    def generate_id(self) -> str:
+        """Generate a unique ID for this node."""
+        return f"BuildModule_{self.path}"
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary for graph storage."""
+        return {
+            "name": self.name,
+            "path": self.path,
+            "manifest": self.manifest,
+            "isModule": self.is_module,
+            "isSystem": self.is_system,
+            "members": list(self.members),
+            "sameAs": self.same_as,
+            "excluded": self.excluded,
+            # Its structural name as the one candidate of the closed-set naming (no naming call)
+            "nameCandidates": [self.name],
+            # Module ids carry no prefix the graph manager reads the repository from
+            "repository_name": self.repository_name,
+            "type": "BuildModule",
+        }
+
+
 @dataclass
 class DeployableUnitNode:
     """A deployable unit: what runs on its own (a container, a declared entry point, a mainframe application).