htmlgraph 0.9.3__py3-none-any.whl → 0.27.5__py3-none-any.whl

htmlgraph/docs/templates/example_user_override.md.j2

@@ -0,0 +1,47 @@
+{# Example user override template - copy to .htmlgraph/docs/templates/agents.md.j2 #}
+{% extends "base_agents.md.j2" %}
+
+{# Override the header to customize branding #}
+{% block header %}
+# 🤖 {{ platform|title }} Agent - Our Team Documentation
+{% endblock %}
+
+{# Add custom team workflows #}
+{% block custom_workflows %}
+## Our Team Conventions
+
+### Daily Workflow
+1. **Morning Standup** - Review `sdk.summary()` for overnight progress
+2. **Pick Task** - Use `sdk.analytics.recommend_next_work()` for priorities
+3. **Daily Feature** - Create with template: `feat-{YYYYMMDD}-{description}`
+4. **End of Day** - Commit with `./scripts/git-commit-push.sh`
+
+### Commit Message Format
+```
+type(scope): description
+
+Examples:
+- feat(auth): add OAuth provider integration
+- fix(api): resolve session timeout bug
+- docs(readme): update installation steps
+```
+
+### Branch Strategy
+- `main` - Production-ready code
+- `feature/*` - New features
+- `fix/*` - Bug fixes
+- `spike/*` - Research and experimentation
+
+### Code Review Checklist
+- [ ] All tests pass
+- [ ] Documentation updated
+- [ ] No sensitive data in code
+- [ ] Ruff and mypy pass
+- [ ] Feature tracked in HtmlGraph
+{% endblock %}
+
+{# You can also override other blocks:
+   - introduction: Project-specific intro
+   - deployment: Team-specific deployment process
+   - footer: Custom footer with team info
+#}

htmlgraph/docs/version_check.py

@@ -0,0 +1,163 @@
+"""
+Version checking and interactive upgrade workflows.
+"""
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from rich.prompt import Prompt
+
+from htmlgraph.docs.docs_version import get_current_doc_version, is_compatible
+from htmlgraph.docs.metadata import DocsMetadata
+from htmlgraph.docs.migrations import get_migration
+
+if TYPE_CHECKING:
+    from htmlgraph.docs.migrations import MigrationScript
+
+
+def check_docs_version(htmlgraph_dir: Path) -> tuple[bool, str | None]:
+    """Check if docs version is compatible.
+
+    Args:
+        htmlgraph_dir: Path to .htmlgraph directory
+
+    Returns:
+        Tuple of (is_compatible, message)
+        - is_compatible: True if compatible
+        - message: Optional warning/error message
+    """
+    metadata = DocsMetadata.load(htmlgraph_dir)
+    current_version = get_current_doc_version()
+
+    if metadata.schema_version == current_version:
+        return True, None
+
+    if is_compatible(metadata.schema_version, current_version):
+        return (
+            True,
+            f"⚠️  Docs version {metadata.schema_version} is supported but outdated (current: {current_version})",
+        )
+
+    return (
+        False,
+        f"❌ Docs version {metadata.schema_version} is incompatible with package (requires: {current_version})",
+    )
+
+
+def upgrade_docs_interactive(htmlgraph_dir: Path) -> None:
+    """Interactive upgrade workflow with user prompts.
+
+    Args:
+        htmlgraph_dir: Path to .htmlgraph directory
+    """
+    metadata = DocsMetadata.load(htmlgraph_dir)
+    current_version = get_current_doc_version()
+
+    if metadata.schema_version == current_version:
+        print("✅ Docs are up to date")
+        return
+
+    # Get migration script
+    migration = get_migration(metadata.schema_version, current_version)
+    if not migration:
+        print(
+            f"❌ No migration available from v{metadata.schema_version} to v{current_version}"
+        )
+        return
+
+    # Show user their options
+    print(
+        f"""
+📋 Documentation Upgrade Available
+  Current: v{metadata.schema_version}
+  Target:  v{current_version}
+
+  Options:
+    1. Auto-migrate (preserves customizations)
+    2. Side-by-side (test before committing)
+    3. Manual migration (view diff first)
+    4. Skip (stay on v{metadata.schema_version})
+  """
+    )
+
+    choice = Prompt.ask("Choose option", choices=["1", "2", "3", "4"], default="4")
+
+    if choice == "1":
+        _auto_migrate(htmlgraph_dir, migration)
+    elif choice == "2":
+        _side_by_side_migrate(htmlgraph_dir, migration)
+    elif choice == "3":
+        _show_diff_for_manual(htmlgraph_dir, migration)
+    else:
+        print("⏭️  Skipping migration")
+
+
+def _auto_migrate(htmlgraph_dir: Path, migration: "MigrationScript") -> None:  # type: ignore[name-defined]
+    """Automatically migrate with backup.
+
+    Args:
+        htmlgraph_dir: Path to .htmlgraph directory
+        migration: MigrationScript instance
+    """
+    backup_dir = htmlgraph_dir / ".docs-backups"
+    backup_dir.mkdir(exist_ok=True)
+
+    print("🚀 Starting auto-migration...")
+    success = migration.migrate(htmlgraph_dir, backup_dir)
+
+    if success:
+        print("✅ Migration complete!")
+        print(f"📦 Backup saved to {backup_dir}")
+    else:
+        print("❌ Migration failed. Docs unchanged.")
+
+
+def _side_by_side_migrate(htmlgraph_dir: Path, migration: "MigrationScript") -> None:  # type: ignore[name-defined]
+    """Create side-by-side versions for testing.
+
+    Args:
+        htmlgraph_dir: Path to .htmlgraph directory
+        migration: MigrationScript instance
+    """
+    print("📋 Creating side-by-side versions...")
+    print("⚠️  Side-by-side migration not yet implemented")
+    print("    Use option 1 (auto-migrate) or 3 (manual) instead")
+
+
+def _show_diff_for_manual(htmlgraph_dir: Path, migration: "MigrationScript") -> None:  # type: ignore[name-defined]
+    """Show diff preview for manual migration.
+
+    Args:
+        htmlgraph_dir: Path to .htmlgraph directory
+        migration: MigrationScript instance
+    """
+    print("📊 Showing migration preview...")
+    print("⚠️  Diff preview not yet implemented")
+    print("    Use option 1 (auto-migrate) instead")
+
+
+def check_version_on_init(htmlgraph_dir: Path, auto_upgrade: bool = False) -> bool:
+    """Check version compatibility on SDK initialization.
+
+    Args:
+        htmlgraph_dir: Path to .htmlgraph directory
+        auto_upgrade: If True, automatically upgrade if safe
+
+    Returns:
+        True if compatible or upgraded successfully
+    """
+    compatible, message = check_docs_version(htmlgraph_dir)
+
+    if compatible and message:
+        # Compatible but outdated
+        print(message)
+        if auto_upgrade:
+            upgrade_docs_interactive(htmlgraph_dir)
+        return True
+
+    if not compatible:
+        print(message)
+        print("\nRun `uv run htmlgraph docs upgrade` to migrate.")
+        return False
+
+    return True

htmlgraph/edge_index.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Edge Index for O(1) reverse edge lookups.
 
@@ -10,13 +12,14 @@ Without this index, finding incoming edges requires scanning all nodes
 in the graph - O(V×E) complexity.
 """
 
-from __future__ import annotations
+
 from collections import defaultdict
+from collections.abc import Iterator
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Iterator
+from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from htmlgraph.models import Node, Edge
+    from htmlgraph.models import Edge, Node
 
 
 @dataclass
@@ -27,14 +30,50 @@ class EdgeRef:
     Stores the essential information needed to identify and traverse
     an edge without holding a reference to the full Edge object.
     """
+
     source_id: str
     target_id: str
     relationship: str
 
     def __hash__(self) -> int:
+        """
+        Compute hash for EdgeRef.
+
+        Enables using EdgeRef in sets and as dict keys.
+
+        Returns:
+            int: Hash value based on source_id, target_id, and relationship
+
+        Example:
+            >>> ref1 = EdgeRef("feat-001", "feat-002", "blocked_by")
+            >>> ref2 = EdgeRef("feat-001", "feat-002", "blocked_by")
+            >>> refs = {ref1, ref2}  # Set deduplication works
+            >>> len(refs)
+            1
+        """
         return hash((self.source_id, self.target_id, self.relationship))
 
     def __eq__(self, other: object) -> bool:
+        """
+        Check equality with another EdgeRef.
+
+        Enables using == operator and set membership checks.
+
+        Args:
+            other: Object to compare with
+
+        Returns:
+            bool: True if both EdgeRefs have same source, target, and relationship
+
+        Example:
+            >>> ref1 = EdgeRef("feat-001", "feat-002", "blocked_by")
+            >>> ref2 = EdgeRef("feat-001", "feat-002", "blocked_by")
+            >>> ref1 == ref2
+            True
+            >>> ref3 = EdgeRef("feat-001", "feat-003", "blocked_by")
+            >>> ref1 == ref3
+            False
+        """
         if not isinstance(other, EdgeRef):
             return False
         return (
@@ -67,8 +106,12 @@ class EdgeIndex:
         blocked = index.get_outgoing("feature-001", relationship="blocks")
     """
 
-    _incoming: dict[str, list[EdgeRef]] = field(default_factory=lambda: defaultdict(list))
-    _outgoing: dict[str, list[EdgeRef]] = field(default_factory=lambda: defaultdict(list))
+    _incoming: dict[str, list[EdgeRef]] = field(
+        default_factory=lambda: defaultdict(list)
+    )
+    _outgoing: dict[str, list[EdgeRef]] = field(
+        default_factory=lambda: defaultdict(list)
+    )
     _edge_count: int = 0
 
     def add(self, source_id: str, target_id: str, relationship: str) -> EdgeRef:
@@ -83,7 +126,9 @@ class EdgeIndex:
         Returns:
             EdgeRef for the added edge
         """
-        ref = EdgeRef(source_id=source_id, target_id=target_id, relationship=relationship)
+        ref = EdgeRef(
+            source_id=source_id, target_id=target_id, relationship=relationship
+        )
 
         # Avoid duplicates
         if ref not in self._incoming[target_id]:
@@ -93,7 +138,7 @@ class EdgeIndex:
 
         return ref
 
-    def add_edge(self, source_id: str, edge: 'Edge') -> EdgeRef:
+    def add_edge(self, source_id: str, edge: Edge) -> EdgeRef:
         """
         Add an edge object to the index.
 
@@ -118,7 +163,9 @@ class EdgeIndex:
         Returns:
             True if edge was removed, False if not found
         """
-        ref = EdgeRef(source_id=source_id, target_id=target_id, relationship=relationship)
+        ref = EdgeRef(
+            source_id=source_id, target_id=target_id, relationship=relationship
+        )
 
         removed = False
         if target_id in self._incoming and ref in self._incoming[target_id]:
@@ -134,7 +181,7 @@ class EdgeIndex:
 
         return removed
 
-    def remove_edge(self, source_id: str, edge: 'Edge') -> bool:
+    def remove_edge(self, source_id: str, edge: Edge) -> bool:
         """
         Remove an edge object from the index.
 
@@ -184,10 +231,88 @@ class EdgeIndex:
         self._edge_count -= removed
         return removed
 
+    def add_node_edges(self, node_id: str, node: Node) -> int:
+        """
+        Add a single node's outgoing edges to the index.
+
+        Args:
+            node_id: Node ID
+            node: Node object with edges to add
+
+        Returns:
+            Number of edges added
+        """
+        added = 0
+        for rel_type, edges in node.edges.items():
+            for edge in edges:
+                self.add(node_id, edge.target_id, rel_type)
+                added += 1
+        return added
+
+    def add_node(self, node_id: str, node: Node) -> int:
+        """
+        Add all edges from a single node to the index.
+
+        Alias for add_node_edges() to match requested API.
+
+        Args:
+            node_id: The node's ID
+            node: The node object with edges attribute
+
+        Returns:
+            Number of edges added
+        """
+        return self.add_node_edges(node_id, node)
+
+    def remove_node_edges(self, node_id: str, node: Node) -> int:
+        """
+        Remove a single node's outgoing edges from the index.
+
+        Args:
+            node_id: Node ID
+            node: Node object with edges to remove
+
+        Returns:
+            Number of edges removed
+        """
+        removed = 0
+        for rel_type, edges in node.edges.items():
+            for edge in edges:
+                if self.remove(node_id, edge.target_id, rel_type):
+                    removed += 1
+        return removed
+
+    def update_node(
+        self, node_id: str, old_node: Node, new_node: Node
+    ) -> tuple[int, int]:
+        """
+        Update a node's edges atomically (remove old, add new).
+
+        This is an atomic operation that removes all edges from the old node
+        and adds all edges from the new node. Useful for updating a node
+        without leaving orphaned edges.
+
+        Args:
+            node_id: The node's ID
+            old_node: The previous node object
+            new_node: The updated node object
+
+        Returns:
+            Tuple of (removed_count, added_count)
+
+        Example:
+            >>> old = Node(id="feat-001", edges={"blocks": [Edge(target_id="feat-002")]})
+            >>> new = Node(id="feat-001", edges={"blocks": [Edge(target_id="feat-003")]})
+            >>> removed, added = index.update_node("feat-001", old, new)
+            >>> print(f"Removed {removed}, added {added}")
+            Removed 1, added 1
+        """
+        removed = self.remove_node_edges(node_id, old_node)
+        added = self.add_node_edges(node_id, new_node)
+        return (removed, added)
+
     def get_incoming(
-        self,
-        target_id: str,
-        relationship: str | None = None
+        self, target_id: str, relationship: str | None = None
     ) -> list[EdgeRef]:
         """
         Get all edges pointing TO a node (O(1) lookup).
@@ -213,9 +338,7 @@ class EdgeIndex:
         return list(edges)
 
     def get_outgoing(
-        self,
-        source_id: str,
-        relationship: str | None = None
+        self, source_id: str, relationship: str | None = None
     ) -> list[EdgeRef]:
         """
         Get all edges pointing FROM a node (O(1) lookup).
@@ -235,10 +358,7 @@ class EdgeIndex:
         return list(edges)
 
     def get_neighbors(
-        self,
-        node_id: str,
-        relationship: str | None = None,
-        direction: str = "both"
+        self, node_id: str, relationship: str | None = None, direction: str = "both"
     ) -> set[str]:
         """
         Get all neighboring node IDs connected to a node.
@@ -263,7 +383,9 @@ class EdgeIndex:
 
         return neighbors
 
-    def has_edge(self, source_id: str, target_id: str, relationship: str | None = None) -> bool:
+    def has_edge(
+        self, source_id: str, target_id: str, relationship: str | None = None
+    ) -> bool:
         """
         Check if an edge exists between two nodes.
 
@@ -281,10 +403,12 @@ class EdgeIndex:
                     return True
         return False
 
-    def rebuild(self, nodes: dict[str, 'Node']) -> int:
+    def rebuild(self, nodes: dict[str, Node]) -> int:
         """
         Rebuild the entire index from a node dictionary.
 
+        Optimized to use add_node_edges() for cleaner code.
+
         Args:
             nodes: Dictionary mapping node_id to Node objects
 
@@ -294,9 +418,7 @@ class EdgeIndex:
         self.clear()
 
         for node_id, node in nodes.items():
-            for relationship, edges in node.edges.items():
-                for edge in edges:
-                    self.add(node_id, edge.target_id, edge.relationship)
+            self.add_node_edges(node_id, node)
 
         return self._edge_count
 
@@ -307,11 +429,44 @@ class EdgeIndex:
         self._edge_count = 0
 
     def __len__(self) -> int:
-        """Return number of edges in the index."""
+        """
+        Get the total number of edges in the index.
+
+        Enables using len() on EdgeIndex instances.
+
+        Returns:
+            int: Total number of edges indexed
+
+        Example:
+            >>> index = EdgeIndex()
+            >>> index.rebuild(graph.nodes)
+            >>> print(f"Index contains {len(index)} edges")
+            Index contains 156 edges
+        """
         return self._edge_count
 
     def __iter__(self) -> Iterator[EdgeRef]:
-        """Iterate over all edges in the index."""
+        """
+        Iterate over all unique edges in the index.
+
+        Enables using EdgeIndex in for loops and other iteration contexts.
+        Deduplicates edges to avoid returning the same edge twice.
+
+        Yields:
+            EdgeRef: Each unique edge in the index
+
+        Example:
+            >>> index = EdgeIndex()
+            >>> index.rebuild(graph.nodes)
+            >>> for edge in index:
+            ...     print(f"{edge.source_id} --{edge.relationship}--> {edge.target_id}")
+            feat-001 --blocked_by--> feat-002
+            feat-003 --related--> feat-001
+
+            >>> # Works with comprehensions
+            >>> blocked_by = [e for e in index if e.relationship == "blocked_by"]
+            >>> blocking_count = len([e for e in index if e.relationship == "blocks"])
+        """
         seen: set[EdgeRef] = set()
         for refs in self._outgoing.values():
             for ref in refs:
@@ -330,5 +485,5 @@ class EdgeIndex:
             "edge_count": self._edge_count,
             "nodes_with_incoming": len(self._incoming),
             "nodes_with_outgoing": len(self._outgoing),
-            "relationships": list(set(ref.relationship for ref in self))
+            "relationships": list(set(ref.relationship for ref in self)),
         }