htmlgraph 0.26.24__py3-none-any.whl → 0.27.0__py3-none-any.whl

htmlgraph/orchestration/task_coordination.py

@@ -1,3 +1,7 @@
+import logging
+
+logger = logging.getLogger(__name__)
+
 """
 Orchestration helpers for reliable parallel task coordination.
 
@@ -7,9 +11,13 @@ Provides Task ID pattern for retrieving results from parallel delegations.
 import time
 import uuid
 from datetime import datetime, timedelta
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
-from htmlgraph.sdk import SDK
+if TYPE_CHECKING:
+    from htmlgraph.sdk import SDK
+else:
+    # Avoid circular import during module initialization
+    SDK = None
 
 
 def generate_task_id() -> str:
@@ -72,7 +80,7 @@ Provide detailed findings in your response.
 
 
 def get_results_by_task_id(
-    sdk: SDK,
+    sdk: "SDK",
     task_id: str,
     timeout: int = 60,
     poll_interval: int = 2,
@@ -138,7 +146,7 @@ def get_results_by_task_id(
 
 
 def parallel_delegate(
-    sdk: SDK,
+    sdk: "SDK",
     tasks: list[dict[str, str]],
     timeout: int = 120,
 ) -> dict[str, dict[str, Any]]:
@@ -161,7 +169,7 @@ def parallel_delegate(
         ])
 
         for task_id, result in results.items():
-            print(f"{task_id}: {result['findings']}")
+            logger.info(f"{task_id}: {result['findings']}")
     """
     # Generate task IDs and enhanced prompts
     task_mapping = {}
@@ -189,7 +197,7 @@ def parallel_delegate(
 
 
 def save_task_results(
-    sdk: SDK,
+    sdk: "SDK",
     task_id: str,
     description: str,
     results: str,
@@ -263,7 +271,7 @@ def save_task_results(
 
 
 def validate_and_save(
-    sdk: SDK,
+    sdk: "SDK",
     task_id: str,
     description: str,
     results: str,
@@ -303,7 +311,7 @@ def validate_and_save(
         )
 
         if outcome["validated"]:
-            print(f"✅ Saved to spike: {outcome['spike_id']}")
+            logger.info(f"✅ Saved to spike: {outcome['spike_id']}")
     """
     validated = True
     validation_results = None

htmlgraph/orchestrator.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 SubagentOrchestrator for context-preserving delegation.
 
@@ -83,7 +85,6 @@ Key Patterns
 4. Parallel execution: Multiple subagents can work simultaneously
 """
 
-from __future__ import annotations
 
 from dataclasses import dataclass, field
 from datetime import datetime

htmlgraph/parallel.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Parallel workflow execution coordinator for multi-agent task processing.
 
@@ -76,7 +78,6 @@ Best Practices:
     - Limit to 3-5 parallel agents for optimal results
 """
 
-from __future__ import annotations
 
 from dataclasses import dataclass, field
 from datetime import datetime

htmlgraph/query_builder.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Fluent Query Builder for HtmlGraph.
 
@@ -24,7 +26,6 @@ Example:
         .execute()
 """
 
-from __future__ import annotations
 
 import re
 from collections.abc import Callable, Iterator

htmlgraph/reflection.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Computational Reflection Module.
 
@@ -23,7 +25,6 @@ Usage:
     # }
 """
 
-from __future__ import annotations
 
 from dataclasses import dataclass
 from datetime import datetime, timedelta

htmlgraph/refs.py

@@ -0,0 +1,344 @@
+from __future__ import annotations
+
+"""
+Short reference manager for graph nodes.
+
+Manages persistent mapping of short refs (@f1, @t2, @b5) to full node IDs,
+enabling AI-friendly snapshots and queries.
+"""
+
+
+import json
+from datetime import datetime
+from pathlib import Path
+
+
+class RefManager:
+    """
+    Manages short references (@f1, @t1, @b5, etc.) for graph nodes.
+
+    Maintains a persistent refs.json file mapping short refs to full node IDs.
+    Refs are stable across sessions and auto-generated on first access.
+
+    Ref format: @{prefix}{number}
+    Prefixes: f=feature, t=track, b=bug, s=spike, c=chore, e=epic, d=todo
+
+    Example:
+        >>> ref_mgr = RefManager(Path(".htmlgraph"))
+        >>> ref = ref_mgr.generate_ref("feat-a1b2c3d4")
+        >>> print(ref)  # "@f1"
+        >>> full_id = ref_mgr.resolve_ref("@f1")
+        >>> print(full_id)  # "feat-a1b2c3d4"
+    """
+
+    # Map node ID prefix to short ref prefix
+    PREFIX_MAP = {
+        "feat": "f",
+        "trk": "t",
+        "bug": "b",
+        "spk": "s",
+        "chr": "c",
+        "epc": "e",
+        "todo": "d",
+        "phs": "p",
+    }
+
+    # Reverse mapping for type lookup
+    TYPE_MAP = {
+        "f": "feature",
+        "t": "track",
+        "b": "bug",
+        "s": "spike",
+        "c": "chore",
+        "e": "epic",
+        "d": "todo",
+        "p": "phase",
+    }
+
+    def __init__(self, graph_dir: Path):
+        """
+        Initialize RefManager.
+
+        Args:
+            graph_dir: Path to .htmlgraph directory
+        """
+        self.graph_dir = Path(graph_dir)
+        self.refs_file = self.graph_dir / "refs.json"
+        self._refs: dict[str, str] = {}  # Maps: "@f1" -> "feat-a1b2c3d4"
+        self._reverse_refs: dict[str, str] = {}  # Maps: "feat-a1b2c3d4" -> "@f1"
+        self._load()
+
+    def _load(self) -> None:
+        """Load refs.json into memory."""
+        if not self.refs_file.exists():
+            self._refs = {}
+            self._reverse_refs = {}
+            return
+
+        try:
+            with open(self.refs_file, encoding="utf-8") as f:
+                data = json.load(f)
+                self._refs = data.get("refs", {})
+
+            # Build reverse mapping
+            self._reverse_refs = {v: k for k, v in self._refs.items()}
+        except (json.JSONDecodeError, OSError) as e:
+            # Corrupted file - start fresh
+            import logging
+
+            logging.warning(f"Failed to load refs.json: {e}. Starting fresh.")
+            self._refs = {}
+            self._reverse_refs = {}
+
+    def _save(self) -> None:
+        """Save refs to refs.json."""
+        # Ensure directory exists
+        self.graph_dir.mkdir(parents=True, exist_ok=True)
+
+        data = {
+            "refs": self._refs,
+            "version": 1,
+            "regenerated_at": datetime.now().isoformat(),
+        }
+
+        try:
+            with open(self.refs_file, "w", encoding="utf-8") as f:
+                json.dump(data, f, indent=2, ensure_ascii=False)
+        except OSError as e:
+            import logging
+
+            logging.error(f"Failed to save refs.json: {e}")
+
+    def _parse_node_type(self, node_id: str) -> str | None:
+        """
+        Extract node type prefix from node ID.
+
+        Args:
+            node_id: Full node ID like "feat-a1b2c3d4"
+
+        Returns:
+            Node type prefix (e.g., "feat") or None if invalid
+        """
+        if "-" not in node_id:
+            return None
+
+        prefix = node_id.split("-", 1)[0]
+        return prefix if prefix in self.PREFIX_MAP else None
+
+    def _next_ref_number(self, prefix: str) -> int:
+        """
+        Get next available ref number for a type.
+
+        Args:
+            prefix: Short ref prefix (e.g., "f", "t", "b")
+
+        Returns:
+            Next available number (1, 2, 3, ...)
+        """
+        # Find all refs with this prefix
+        existing = [int(ref[2:]) for ref in self._refs if ref.startswith(f"@{prefix}")]
+        return max(existing, default=0) + 1
+
+    def generate_ref(self, node_id: str) -> str:
+        """
+        Generate a short ref for a node ID.
+
+        This method is idempotent - calling it multiple times with the same
+        node_id returns the same ref without creating duplicates.
+
+        Args:
+            node_id: Full node ID like "feat-a1b2c3d4"
+
+        Returns:
+            Short ref like "@f1"
+
+        Raises:
+            ValueError: If node_id has invalid format
+
+        Example:
+            >>> ref = ref_mgr.generate_ref("feat-abc123")
+            >>> print(ref)  # "@f1"
+            >>> # Second call returns same ref
+            >>> ref2 = ref_mgr.generate_ref("feat-abc123")
+            >>> assert ref == ref2
+        """
+        # Check if already has ref (idempotent)
+        if node_id in self._reverse_refs:
+            return self._reverse_refs[node_id]
+
+        # Parse node type
+        node_prefix = self._parse_node_type(node_id)
+        if not node_prefix:
+            raise ValueError(f"Invalid node ID format: {node_id}")
+
+        # Get short prefix
+        short_prefix = self.PREFIX_MAP[node_prefix]
+
+        # Generate next ref
+        number = self._next_ref_number(short_prefix)
+        short_ref = f"@{short_prefix}{number}"
+
+        # Store mappings
+        self._refs[short_ref] = node_id
+        self._reverse_refs[node_id] = short_ref
+
+        # Persist
+        self._save()
+
+        return short_ref
+
+    def get_ref(self, node_id: str) -> str | None:
+        """
+        Get existing ref for a node ID (create if not exist).
+
+        Args:
+            node_id: Full node ID like "feat-a1b2c3d4"
+
+        Returns:
+            Short ref like "@f1", or None if node_id invalid
+
+        Example:
+            >>> ref = ref_mgr.get_ref("feat-abc123")
+            >>> # Creates ref if doesn't exist
+        """
+        # Return existing ref
+        if node_id in self._reverse_refs:
+            return self._reverse_refs[node_id]
+
+        # Generate new ref if valid node ID
+        try:
+            return self.generate_ref(node_id)
+        except ValueError:
+            return None
+
+    def resolve_ref(self, short_ref: str) -> str | None:
+        """
+        Resolve short ref to full node ID.
+
+        Args:
+            short_ref: "@f1", "@t2", etc.
+
+        Returns:
+            Full node ID or None if not found
+
+        Example:
+            >>> full_id = ref_mgr.resolve_ref("@f1")
+            >>> print(full_id)  # "feat-abc123"
+        """
+        return self._refs.get(short_ref)
+
+    def get_all_refs(self) -> dict[str, str]:
+        """
+        Return all refs.
+
+        Returns:
+            Dict mapping short refs to full IDs: {"@f1": "feat-a1b2c3d4", ...}
+        """
+        return self._refs.copy()
+
+    def get_refs_by_type(self, node_type: str) -> list[tuple[str, str]]:
+        """
+        Get all refs for a specific type.
+
+        Args:
+            node_type: "feature", "track", "bug", "spike", "chore", "epic", "todo", "phase"
+
+        Returns:
+            List of (short_ref, full_id) tuples sorted by ref number
+
+        Example:
+            >>> feature_refs = ref_mgr.get_refs_by_type("feature")
+            >>> for ref, full_id in feature_refs:
+            ...     print(f"{ref} -> {full_id}")
+        """
+        # Get prefix for this type
+        prefix = None
+        for short_prefix, type_name in self.TYPE_MAP.items():
+            if type_name == node_type:
+                prefix = short_prefix
+                break
+
+        if not prefix:
+            return []
+
+        # Filter refs by prefix
+        matching = [
+            (ref, full_id)
+            for ref, full_id in self._refs.items()
+            if ref.startswith(f"@{prefix}")
+        ]
+
+        # Sort by ref number
+        def sort_key(item: tuple[str, str]) -> int:
+            ref = item[0]
+            try:
+                return int(ref[2:])  # Extract number after "@f"
+            except (ValueError, IndexError):
+                return 0
+
+        return sorted(matching, key=sort_key)
+
+    def rebuild_refs(self) -> None:
+        """
+        Rebuild refs from all .htmlgraph/ files (recovery tool).
+
+        Scans all collection directories (features/, tracks/, bugs/, etc.)
+        and rebuilds refs.json from scratch. Preserves existing refs where
+        possible to maintain stability.
+
+        This is a recovery tool for when refs.json is corrupted or deleted.
+
+        Example:
+            >>> ref_mgr.rebuild_refs()
+            >>> # Refs regenerated from file system
+        """
+        # Save current refs for preservation
+        old_refs = self._refs.copy()
+
+        # Clear in-memory refs
+        self._refs = {}
+        self._reverse_refs = {}
+
+        # Scan all collection directories
+        collections = [
+            "features",
+            "tracks",
+            "bugs",
+            "spikes",
+            "chores",
+            "epics",
+            "todos",
+            "phases",
+        ]
+
+        for collection in collections:
+            collection_dir = self.graph_dir / collection
+            if not collection_dir.exists():
+                continue
+
+            # Scan HTML files
+            for html_file in collection_dir.glob("*.html"):
+                # Extract node ID from filename (without .html)
+                node_id = html_file.stem
+
+                # Skip if invalid format
+                if not self._parse_node_type(node_id):
+                    continue
+
+                # Try to preserve existing ref
+                if node_id in {v for v in old_refs.values()}:
+                    # Find old ref
+                    old_ref = next(
+                        (k for k, v in old_refs.items() if v == node_id), None
+                    )
+                    if old_ref:
+                        # Preserve old ref
+                        self._refs[old_ref] = node_id
+                        self._reverse_refs[node_id] = old_ref
+                        continue
+
+                # Generate new ref
+                self.generate_ref(node_id)
+
+        # Save to disk
+        self._save()

htmlgraph/repo_hash.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Repository Hashing and Git Awareness Module.
 
@@ -22,7 +24,6 @@ Architecture:
     - monorepo_project: "project-name" (if in monorepo)
 """
 
-from __future__ import annotations
 
 import hashlib
 import logging