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

htmlgraph/ids.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Hash-based ID generation for HtmlGraph.
 
@@ -15,7 +17,6 @@ collision probability is effectively zero even with thousands
 of concurrent agents creating tasks simultaneously.
 """
 
-from __future__ import annotations
 
 import hashlib
 import os
@@ -25,8 +26,18 @@ from typing import Literal
 
 # Type alias for valid node types
 NodeType = Literal[
-    "feature", "bug", "chore", "spike", "epic",
-    "session", "track", "phase", "agent", "spec", "plan", "event"
+    "feature",
+    "bug",
+    "chore",
+    "spike",
+    "epic",
+    "session",
+    "track",
+    "phase",
+    "agent",
+    "spec",
+    "plan",
+    "event",
 ]
 
 # Prefix mapping for human readability
@@ -50,8 +61,8 @@ PREFIXES: dict[str, str] = {
 PREFIX_TO_TYPE: dict[str, str] = {v: k for k, v in PREFIXES.items()}
 
 # Regex patterns for ID validation
-HASH_ID_PATTERN = re.compile(r'^([a-z]{3,4})-([a-f0-9]{8})(\.\d+)*$')
-LEGACY_ID_PATTERN = re.compile(r'^([a-z]+)-(\d{8}-\d{6})$')
+HASH_ID_PATTERN = re.compile(r"^([a-z]{3,4})-([a-f0-9]{8})(\.\d+)*$")
+LEGACY_ID_PATTERN = re.compile(r"^([a-z]+)-(\d{8}-\d{6})$")
 
 
 def generate_id(
@@ -166,15 +177,15 @@ def parse_id(node_id: str) -> dict[str, str | int | list[int] | None]:
         hierarchy = []
         base_id = f"{prefix}-{hash_part}"
         if len(node_id) > len(base_id):
-            hierarchy_str = node_id[len(base_id):]  # e.g., ".1.2"
-            hierarchy = [int(x) for x in hierarchy_str.split('.') if x]
+            hierarchy_str = node_id[len(base_id) :]  # e.g., ".1.2"
+            hierarchy = [int(x) for x in hierarchy_str.split(".") if x]
 
         return {
-            'prefix': prefix,
-            'node_type': PREFIX_TO_TYPE.get(prefix, prefix),
-            'hash': hash_part,
-            'hierarchy': hierarchy,
-            'is_legacy': False,
+            "prefix": prefix,
+            "node_type": PREFIX_TO_TYPE.get(prefix, prefix),
+            "hash": hash_part,
+            "hierarchy": hierarchy,
+            "is_legacy": False,
         }
 
     # Try legacy format (feature-20241222-143022)
@@ -184,20 +195,20 @@ def parse_id(node_id: str) -> dict[str, str | int | list[int] | None]:
         timestamp = legacy_match.group(2)
 
         return {
-            'prefix': prefix,
-            'node_type': prefix,  # Legacy uses full type as prefix
-            'hash': timestamp,
-            'hierarchy': [],
-            'is_legacy': True,
+            "prefix": prefix,
+            "node_type": prefix,  # Legacy uses full type as prefix
+            "hash": timestamp,
+            "hierarchy": [],
+            "is_legacy": True,
         }
 
     # Unknown format
     return {
-        'prefix': None,
-        'node_type': None,
-        'hash': None,
-        'hierarchy': [],
-        'is_legacy': None,
+        "prefix": None,
+        "node_type": None,
+        "hash": None,
+        "hierarchy": [],
+        "is_legacy": None,
     }
 
 
@@ -261,10 +272,10 @@ def get_parent_id(node_id: str) -> str | None:
         >>> get_parent_id("feat-a1b2c3d4")
         None
     """
-    if '.' not in node_id:
+    if "." not in node_id:
         return None
 
-    return node_id.rsplit('.', 1)[0]
+    return node_id.rsplit(".", 1)[0]
 
 
 def get_root_id(node_id: str) -> str:
@@ -284,9 +295,9 @@ def get_root_id(node_id: str) -> str:
         'feat-a1b2c3d4'
     """
     parsed = parse_id(node_id)
-    if parsed['prefix'] and parsed['hash']:
+    if parsed["prefix"] and parsed["hash"]:
         return f"{parsed['prefix']}-{parsed['hash']}"
-    return node_id.split('.')[0]
+    return node_id.split(".")[0]
 
 
 def get_depth(node_id: str) -> int:
@@ -308,4 +319,7 @@ def get_depth(node_id: str) -> int:
         2
     """
     parsed = parse_id(node_id)
-    return len(parsed.get('hierarchy', []))
+    hierarchy = parsed.get("hierarchy", [])
+    if isinstance(hierarchy, list):
+        return len(hierarchy)
+    return 0

htmlgraph/index.d.ts

@@ -0,0 +1,286 @@
+/**
+ * HtmlGraph TypeScript Type Definitions
+ *
+ * Python SDK type definitions for TypeScript/JavaScript interoperability
+ * when using HtmlGraph via tools like pyodide or similar bridges.
+ */
+
+// ============================================================================
+// Core Types
+// ============================================================================
+
+export interface Step {
+    description: string;
+    completed: boolean;
+    agent?: string;
+    timestamp?: string;
+}
+
+export interface Edge {
+    target_id: string;
+    title?: string;
+    relationship?: string;
+}
+
+export interface Node {
+    id: string;
+    title: string;
+    type: string;
+    status: string;
+    priority: string;
+    created: string;
+    updated: string;
+    content?: string;
+    tags?: string[];
+    steps?: Step[];
+    edges?: Record<string, Edge[]>;
+    track?: string;
+    agent_assigned?: string;
+}
+
+export interface Feature extends Node {
+    type: 'feature';
+}
+
+export interface Bug extends Node {
+    type: 'bug';
+}
+
+export interface Chore extends Node {
+    type: 'chore';
+    maintenance_type?: 'corrective' | 'adaptive' | 'perfective' | 'preventive';
+    technical_debt_score?: number;
+}
+
+export interface Spike extends Node {
+    type: 'spike';
+    spike_type?: 'technical' | 'architectural' | 'risk' | 'general';
+    timebox_hours?: number;
+    findings?: string;
+    decision?: string;
+}
+
+export interface Requirement {
+    description: string;
+    priority: 'must-have' | 'should-have' | 'nice-to-have';
+}
+
+export interface AcceptanceCriteria {
+    description: string;
+    test_case: string;
+}
+
+export interface Spec {
+    overview: string;
+    context?: string;
+    requirements: Requirement[];
+    acceptance_criteria?: AcceptanceCriteria[];
+}
+
+export interface Task {
+    description: string;
+    estimated_hours?: number;
+}
+
+export interface Phase {
+    name: string;
+    tasks: Task[];
+}
+
+export interface Plan {
+    phases: Phase[];
+    total_estimated_hours?: number;
+}
+
+export interface Track {
+    id: string;
+    title: string;
+    description?: string;
+    priority: string;
+    status: string;
+    created: string;
+    updated: string;
+    spec?: Spec;
+    plan?: Plan;
+}
+
+// ============================================================================
+// Analytics Types
+// ============================================================================
+
+export interface Bottleneck {
+    id: string;
+    title: string;
+    status: string;
+    priority: string;
+    blocks_count: number;
+    impact_score: number;
+    blocked_tasks: string[];
+}
+
+export interface Recommendation {
+    id: string;
+    title: string;
+    priority: string;
+    score: number;
+    reasons: string[];
+    estimated_hours?: number;
+    unlocks_count: number;
+    unlocks: string[];
+}
+
+export interface ParallelWork {
+    max_parallelism: number;
+    ready_now: number;
+    total_ready: number;
+    level_count: number;
+    next_level: string[][];
+}
+
+export interface Risk {
+    high_risk_count: number;
+    high_risk_tasks: Array<{
+        id: string;
+        title: string;
+        risk_factors: string[];
+    }>;
+    circular_dependencies: string[][];
+    orphaned_count: number;
+    recommendations: string[];
+}
+
+export interface Impact {
+    node_id: string;
+    direct_dependents: string[];
+    total_impact: number;
+    completion_impact: number;
+    unlocks_count: number;
+    affected_tasks: string[];
+}
+
+// ============================================================================
+// Collection Interface
+// ============================================================================
+
+export interface Collection<T extends Node> {
+    /**
+     * Get all nodes in the collection
+     */
+    all(): T[];
+
+    /**
+     * Get a single node by ID
+     */
+    get(id: string): T | null;
+
+    /**
+     * Query nodes matching criteria
+     */
+    where(filters: Partial<T>): T[];
+
+    /**
+     * Create a new node (returns builder for features)
+     */
+    create(title: string): T | FeatureBuilder;
+
+    /**
+     * Edit a node with context manager-like behavior
+     */
+    edit(id: string): EditContext<T>;
+
+    /**
+     * Batch update multiple nodes
+     */
+    batch_update(ids: string[], updates: Partial<T>): void;
+
+    /**
+     * Mark nodes as done
+     */
+    mark_done(ids: string[]): void;
+
+    /**
+     * Assign nodes to an agent
+     */
+    assign(ids: string[], agent: string): void;
+}
+
+// ============================================================================
+// Builder Interfaces
+// ============================================================================
+
+export interface FeatureBuilder {
+    set_priority(priority: string): FeatureBuilder;
+    set_description(description: string): FeatureBuilder;
+    set_track(track_id: string): FeatureBuilder;
+    add_steps(steps: string[]): FeatureBuilder;
+    add_tags(tags: string[]): FeatureBuilder;
+    blocked_by(feature_ids: string[]): FeatureBuilder;
+    save(): Feature;
+}
+
+export interface TrackBuilder {
+    title(title: string): TrackBuilder;
+    description(description: string): TrackBuilder;
+    priority(priority: string): TrackBuilder;
+    with_spec(spec: {
+        overview: string;
+        context?: string;
+        requirements: Array<[string, string] | string>;
+        acceptance_criteria?: Array<[string, string] | string>;
+    }): TrackBuilder;
+    with_plan_phases(phases: Array<[string, string[]]>): TrackBuilder;
+    create(): Track;
+}
+
+export interface EditContext<T> {
+    __enter__(): T;
+    __exit__(): void;
+}
+
+// ============================================================================
+// SDK Interface
+// ============================================================================
+
+export interface SDK {
+    agent: string;
+
+    // Collections
+    features: Collection<Feature>;
+    bugs: Collection<Bug>;
+    chores: Collection<Chore>;
+    spikes: Collection<Spike>;
+    epics: Collection<Node>;
+    phases: Collection<Node>;
+    tracks: {
+        all(): Track[];
+        get(id: string): Track | null;
+        builder(): TrackBuilder;
+    };
+
+    // Analytics
+    find_bottlenecks(options?: { top_n?: number }): Bottleneck[];
+    recommend_next_work(options?: { agent_count?: number }): Recommendation[];
+    get_parallel_work(options?: { max_agents?: number }): ParallelWork;
+    assess_risks(): Risk;
+    analyze_impact(node_id: string): Impact;
+}
+
+// ============================================================================
+// Factory Functions
+// ============================================================================
+
+/**
+ * Create a new SDK instance
+ */
+export function SDK(options?: { agent?: string }): SDK;
+
+/**
+ * Create a new HtmlGraph instance
+ */
+export function HtmlGraph(directory: string): any;
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export default SDK;