sysmlpy 0.78.0__tar.gz → 0.79.0__tar.gz

{sysmlpy-0.78.0 → sysmlpy-0.79.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sysmlpy
-Version: 0.78.0
+Version: 0.79.0
 Summary: 
 License-File: LICENSE
 Author: Jon R. Fox (mycr0ft)

{sysmlpy-0.78.0 → sysmlpy-0.79.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "sysmlpy"
-version = "0.78.0"
+version = "0.79.0"
 description = ""
 authors = [{ name = "Jon R. Fox (mycr0ft)", email = "jon.fox@drfox.com" }]
 readme = "README.md"

{sysmlpy-0.78.0 → sysmlpy-0.79.0}/src/sysmlpy/__init__.py

@@ -34,7 +34,7 @@ __all__ = [
     "render_state_transition_view_svg", "boxes_view",
 ]
 __author__ = "Jon Fox"
-__version__ = "0.78.0"
+__version__ = "0.79.0"
 
 from sysmlpy.usage import (
     Item, Attribute, Part, Port, Action, Reference, UseCase, Requirement, Interface, Message,

{sysmlpy-0.78.0 → sysmlpy-0.79.0}/src/sysmlpy/definition.py

@@ -117,6 +117,7 @@ class Model(Searchable):
                     p = Package().load_from_grammar(
                         PackageGrammar(de["ownedRelatedElement"])
                     )
+                    p.parent = self
                     self.children.append(p)
                     member_grammar.append(p._get_definition(child="PackageBody"))
                 elif found_package:
@@ -164,6 +165,7 @@ class Model(Searchable):
                 p = Package().load_from_grammar(
                     PackageGrammar(synthetic_definition)
                 )
+                p.parent = self
                 self.children.append(p)
                 member_grammar.append(p._get_definition(child="PackageBody"))
             else:
@@ -429,6 +431,130 @@ class Model(Searchable):
                     return path
         return None
 
+    def resolve_types(self) -> int:
+        """Resolve every usage's declared type name to its definition object.
+
+        ``loads()`` preserves the *declared type name* on usages
+        (``usage.typed_by_name``), but the resolved definition *object*
+        (``usage.typedby``) is only set when the model is wired
+        programmatically via ``set_type()`` / ``set_typed_by()``.  This
+        pass closes that gap: it indexes every definition in the model
+        (by simple name and by ``::``-qualified namespace path) and
+        links each usage's typing to the matching definition object.
+
+        Returns
+        -------
+        int
+            The number of usages resolved by this call.
+
+        Notes
+        -----
+        - Library typings (e.g. ``ScalarValues::Real``) match no
+          definition in the model and are left untouched —
+          :func:`~sysmlpy.analyze` already reports those as unresolved.
+        - Names that resolve to no definition are left untouched.
+        - An ambiguous simple name (same definition name in several
+          packages) resolves to the definition in the usage's own
+          package when one exists, otherwise to the first definition
+          in document order.
+        - Resolution is idempotent: already-linked elements are
+          skipped, and a second call returns ``0``.
+        - ``Reference``-kind elements store the link in ``ref_type``
+          (mirroring ``set_type``); other usages store it in
+          ``typedby``.  Serialization is unaffected either way —
+          ``dump()`` output is identical before and after resolution.
+        """
+        # ---- index definitions -------------------------------------
+        by_qualified = {}   # "Pkg::Engine" -> definition
+        by_simple = {}      # "Engine" -> [definitions in doc order]
+        pkg_paths = {}      # id(package) -> qualified name parts
+
+        def _index(elem, path):
+            for child in getattr(elem, "children", []) or []:
+                name = getattr(child, "name", None)
+                is_package = getattr(child, "sysml_type", None) == "package"
+                is_definition = getattr(child, "is_definition", False)
+                if not (is_package or is_definition):
+                    continue
+                if not name:
+                    _index(child, path)
+                    continue
+                child_path = path + [name]
+                by_qualified.setdefault("::".join(child_path), child)
+                by_simple.setdefault(name, []).append(child)
+                if is_package:
+                    pkg_paths[id(child)] = child_path
+                _index(child, child_path)
+
+        _index(self, [])
+
+        def _lookup(type_name, packages):
+            """Resolve a declared type name to a definition.
+
+            Tries the name as an absolute qualified path first, then as
+            a path relative to each enclosing package (nearest first) —
+            ``Types::Wheel`` declared inside package ``Vehicle`` matches
+            ``Vehicle::Types::Wheel``.
+            """
+            if "::" in type_name:
+                hit = by_qualified.get(type_name)
+                if hit is not None:
+                    return hit
+                parts = type_name.split("::")
+                for pkg in reversed(packages):
+                    prefix = pkg_paths.get(id(pkg), [])
+                    hit = by_qualified.get("::".join(prefix + parts))
+                    if hit is not None:
+                        return hit
+                return None
+            if "." in type_name:
+                # Feature-chain (dotted) names are not type paths.
+                return None
+            candidates = by_simple.get(type_name, [])
+            if len(candidates) == 1:
+                return candidates[0]
+            if len(candidates) > 1:
+                # Prefer the definition in the usage's own package
+                # (nearest enclosing scope), else first in doc order.
+                for pkg in reversed(packages):
+                    for cand in candidates:
+                        if getattr(cand, "parent", None) is pkg:
+                            return cand
+                return candidates[0]
+            return None
+
+        # ---- link usages --------------------------------------------
+        resolved = 0
+
+        def _walk(elem, packages):
+            nonlocal resolved
+            for child in getattr(elem, "children", []) or []:
+                type_name = getattr(child, "_typed_by_name", None)
+                if type_name and not isinstance(type_name, str):
+                    type_name = None
+                if type_name:
+                    has_typedby = hasattr(child, "typedby")
+                    has_ref = hasattr(child, "ref_type")
+                    already = (
+                        (has_typedby and child.typedby is not None)
+                        or (has_ref and child.ref_type is not None)
+                    )
+                    if not already:
+                        target = _lookup(type_name, packages)
+                        if target is not None:
+                            if has_ref:
+                                child.ref_type = target
+                            if has_typedby:
+                                child.typedby = target
+                            resolved += 1
+                child_packages = packages
+                if getattr(child, "sysml_type", None) == "package":
+                    child_packages = packages + [child]
+                _walk(child, child_packages)
+
+        _walk(self, [])
+        return resolved
+
 
 class Package(Searchable):
     """SysML v2 Package.  Exposes typed accessors and ``find()`` / ``all()``

{sysmlpy-0.78.0 → sysmlpy-0.79.0}/src/sysmlpy/store.py

@@ -2468,6 +2468,211 @@ class CayleyStore(Store):
             "avg_degree": (2 * e) / n if n > 0 else 0,
         }
 
+    # ── Query extensions (parity with NetworkX/Kuzu) ────────────────────
+    #
+    # Cayley gizmo has no unbounded path enumeration or server-side
+    # aggregation over predicates, so these run client-side over the
+    # existing primitives (relationships/children/parents/ids).  Results
+    # match the NetworkX/Kuzu shapes; see tests/store_test.py
+    # (TestCayleyQueryExtensions).
+
+    def all_paths(self, source_id: str, target_id: str,
+                  rel_type: Optional[str] = None,
+                  max_paths: int = 20) -> list[list[str]]:
+        """Find up to *max_paths* simple paths between two elements.
+
+        Mirrors :meth:`NetworkXStore.all_paths`.  Depth-first enumeration
+        over relationship edges (any type when *rel_type* is None).
+        """
+        if not self.has(source_id) or not self.has(target_id):
+            return []
+        results: list[list[str]] = []
+
+        def _dfs(node: str, path: list[str]) -> None:
+            if len(results) >= max_paths:
+                return
+            if node == target_id:
+                results.append(list(path))
+                return
+            for nxt, _rt, _d in self.relationships(
+                    node, rel_type=rel_type, direction="out"):
+                if nxt in path:  # simple paths only
+                    continue
+                path.append(nxt)
+                _dfs(nxt, path)
+                path.pop()
+
+        _dfs(source_id, [source_id])
+        return results
+
+    def in_degree_centrality(self, rel_type: Optional[str] = None) -> dict[str, float]:
+        """In-degree fraction per element (how many elements reference *me*).
+
+        Mirrors :meth:`NetworkXStore.in_degree_centrality` (degree divided
+        by ``n - 1``).
+        """
+        n = len(self)
+        if n <= 1:
+            return {eid: 0.0 for eid in self.ids()}
+        denom = n - 1
+        return {
+            eid: len(self.relationships(eid, rel_type=rel_type,
+                                        direction="in")) / denom
+            for eid in self.ids()
+        }
+
+    def out_degree_centrality(self, rel_type: Optional[str] = None) -> dict[str, float]:
+        """Out-degree fraction per element (how many elements *I* reference)."""
+        n = len(self)
+        if n <= 1:
+            return {eid: 0.0 for eid in self.ids()}
+        denom = n - 1
+        return {
+            eid: len(self.relationships(eid, rel_type=rel_type,
+                                        direction="out")) / denom
+            for eid in self.ids()
+        }
+
+    def descendants_depth_limited(self, root_id: str, max_depth: int = 3,
+                                  rel_type: str = REL_PARENT_CHILD) -> list[str]:
+        """Descendants within *max_depth* levels of *root_id*.
+
+        Mirrors :meth:`NetworkXStore.descendants_depth_limited` —
+        breadth-first, each level sorted for deterministic output.
+        """
+        if not self.has(root_id):
+            return []
+        result: list[str] = []
+        frontier = {root_id}
+        visited = {root_id}
+        for _ in range(max_depth):
+            nxt: set[str] = set()
+            for node in frontier:
+                for child in self.children(node, rel_type):
+                    if child not in visited:
+                        nxt.add(child)
+            visited |= nxt
+            result.extend(sorted(nxt))
+            frontier = nxt
+            if not frontier:
+                break
+        return result
+
+    def neighborhood(self, element_id: str, radius: int = 2,
+                     rel_type: Optional[str] = None) -> set[str]:
+        """Ego-neighborhood of *element_id* within *radius* hops.
+
+        Follows edges in both directions (like NetworkX's undirected
+        ego graph); includes the element itself.
+        """
+        if not self.has(element_id):
+            return set()
+        seen = {element_id}
+        frontier = {element_id}
+        for _ in range(radius):
+            nxt: set[str] = set()
+            for node in frontier:
+                for other, _rt, _d in self.relationships(
+                        node, rel_type=rel_type, direction="both"):
+                    if other not in seen:
+                        nxt.add(other)
+            seen |= nxt
+            frontier = nxt
+            if not frontier:
+                break
+        return seen
+
+    def impact_analysis(self, element_id: str,
+                        rel_types: Optional[list[str]] = None,
+                        direction: str = "downstream") -> set[str]:
+        """Elements transitively affected by changes to *element_id*.
+
+        Mirrors :meth:`NetworkXStore.impact_analysis` — *downstream*
+        follows outgoing edges (what I affect), *upstream* follows
+        incoming edges (what affects me).
+        """
+        if not self.has(element_id):
+            return set()
+        dirn = "out" if direction == "downstream" else "in"
+        seen = {element_id}
+        frontier = [element_id]
+        while frontier:
+            current = frontier.pop()
+            for other, rt, _d in self.relationships(current, direction=dirn):
+                if rel_types and rt not in rel_types:
+                    continue
+                if other not in seen:
+                    seen.add(other)
+                    frontier.append(other)
+        seen.discard(element_id)
+        return seen
+
+    def siblings(self, element_id: str) -> list[str]:
+        """Elements sharing a structural parent with *element_id*.
+
+        Mirrors :meth:`KuzuStore.siblings` (parent-child edges only);
+        deterministic parent-then-child order, self excluded.
+        """
+        result: list[str] = []
+        for parent in self.parents(element_id):
+            for sib in self.children(parent):
+                if sib != element_id and sib not in result:
+                    result.append(sib)
+        return result
+
+    def hub_elements(self, min_degree: int = 3,
+                     direction: str = "outgoing") -> list[tuple[str, int]]:
+        """Elements with high relationship degree.
+
+        Mirrors :meth:`KuzuStore.hub_elements` — *(element_id, degree)*
+        pairs with degree ≥ *min_degree*, sorted by degree descending.
+        *direction* selects which edge direction to count.
+        """
+        dirn = {"outgoing": "out", "incoming": "in", "both": "both"}.get(direction)
+        if dirn is None:
+            raise ValueError(
+                f"direction must be 'outgoing', 'incoming' or 'both', "
+                f"got {direction!r}")
+        counts: list[tuple[str, int]] = []
+        for eid in self.ids():
+            degree = len(self.relationships(eid, direction=dirn))
+            if degree >= min_degree:
+                counts.append((eid, degree))
+        counts.sort(key=lambda kv: (-kv[1], kv[0]))
+        return counts
+
+    def shortest_path_between_named(self, source_name: str, target_name: str,
+                                    max_hops: int = 10) -> Optional[list[str]]:
+        """Shortest structural path between two *named* elements.
+
+        Mirrors :meth:`KuzuStore.shortest_path_between_named` — BFS over
+        all relationship types, one hop-level at a time up to *max_hops*;
+        returns the ID path or ``None`` when disconnected.  When several
+        elements share a name, the first path reaching any target wins.
+        """
+        sources = self.query(name=source_name)
+        targets = set(self.query(name=target_name))
+        if not sources or not targets:
+            return None
+        # Multi-source BFS, one level per hop.
+        frontier = {sid: [sid] for sid in sources}
+        visited = set(sources)
+        for _ in range(max_hops):
+            nxt_frontier = {}
+            for node, path in frontier.items():
+                for other, _rt, _d in self.relationships(node, direction="out"):
+                    if other in visited:
+                        continue
+                    new_path = path + [other]
+                    if other in targets:
+                        return new_path
+                    visited.add(other)
+                    nxt_frontier[other] = new_path
+            if not nxt_frontier:
+                break
+            frontier = nxt_frontier
+        return None
+
 
 # ── ID Generation ───────────────────────────────────────────────────────────
 

{sysmlpy-0.78.0 → sysmlpy-0.79.0}/src/sysmlpy/usage.py

@@ -398,6 +398,44 @@ class Usage(Searchable):
         """
         return getattr(self, '_typed_by_name', None)
 
+    def _typedby_serialized_elsewhere(self):
+        """True when ``self.typedby`` is already a member of the model tree.
+
+        The ``_get_definition`` output inserts the typed-by definition
+        as a sibling member so that a *standalone* programmatic usage
+        (one wired via ``set_typed_by`` whose definition was never
+        added to a package) still serializes completely.  When the
+        definition is already part of the enclosing tree — the case
+        for every parsed model, where ``resolve_types()`` fills in
+        ``typedby`` — the insertion would duplicate it (the definition
+        is serialized by its own package), so it must be skipped.
+
+        Walks up ``parent`` to the tree root, then searches the tree
+        excluding this element's own subtree.  O(model size) per typed
+        usage; ``dump()`` is not a hot path.
+        """
+        target = self.typedby
+        if target is None:
+            return False
+        root = self
+        depth = 0
+        while getattr(root, "parent", None) is not None and depth < 1000:
+            root = root.parent
+            depth += 1
+        stack = [root]
+        while stack:
+            node = stack.pop()
+            for child in getattr(node, "children", []) or []:
+                if child is self:
+                    # Don't descend into our own subtree: the question
+                    # is whether the definition is serialized anywhere
+                    # *else*.
+                    continue
+                if child is target:
+                    return True
+                stack.append(child)
+        return False
+
     def _get_definition(self, child=None):
         """Build the grammar tree dict for this element.
 
@@ -429,8 +467,12 @@ class Usage(Searchable):
                 "prefix": None,
             }
 
-        # Add the typed by definition to the package output
-        if self.typedby is not None:
+        # Add the typed by definition to the package output — but only
+        # when it is not already part of the tree (a parsed model whose
+        # ``typedby`` was filled in by ``Model.resolve_types()`` already
+        # serializes the definition from its own package; inserting it
+        # again would duplicate it).
+        if self.typedby is not None and not self._typedby_serialized_elsewhere():
             if child is None:
                 package["ownedRelationship"].insert(
                     0, self.typedby._get_definition(child="PackageBody")
@@ -4552,8 +4594,12 @@ class DefaultReference(Usage):
                 "prefix": None,
             }
 
-        # Add the typed by definition to the package output
-        if self.typedby is not None:
+        # Add the typed by definition to the package output — but only
+        # when it is not already part of the tree (a parsed model whose
+        # ``typedby`` was filled in by ``Model.resolve_types()`` already
+        # serializes the definition from its own package; inserting it
+        # again would duplicate it).
+        if self.typedby is not None and not self._typedby_serialized_elsewhere():
             if child is None:
                 package["ownedRelationship"].insert(
                     0, self.typedby._get_definition(child="PackageBody")