@voodocs/cli 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+## [0.1.2] - 2025-12-19
+
+### Fixed
+- Fixed bug in documentation generator where `class_invariants` was incorrectly referenced as `invariants` on line 570
+- Function-level invariants now render correctly in generated documentation
+
+### Added
+- Comprehensive example file demonstrating function-level invariants (`examples/test_function_invariants.py`)
+- Examples showing `transfer_funds()`, `binary_search()`, and `BankAccount` class with invariants
+- Documentation in USAGE.md clarifying when to use `invariants` vs `class_invariants`
+- Real-world examples of conservation laws and state constraints using invariants
+
+### Changed
+- Updated USAGE.md annotation fields table to clarify `invariants` usage
+- Added "Function with Invariants" and "Class with Invariants" examples to USAGE.md
+
+### Documentation
+- Clarified that `invariants` can be used at function level for execution-time properties
+- Clarified that `class_invariants` should be used for object state constraints
+- Added examples showing both use cases
+
 ## [0.1.1] - 2025-12-19
 
 ### Fixed

package/USAGE.md

@@ -247,7 +247,7 @@ function myFunction(x: number): number {
 | `assumptions` | Assumptions made by the module. |
 | `preconditions` | Conditions that must be true before a function is called. |
 | `postconditions` | Conditions that must be true after a function returns. |
-| `invariants` | Conditions that must always be true for a class. |
+| `invariants` | Properties that remain unchanged throughout execution. For functions: conditions that hold during execution. For classes: use `class_invariants` for object state constraints. |
 | `complexity` | Time and space complexity of an algorithm. |
 | `error_cases` | How the function behaves in error scenarios. |
 | `security_model` | Security implications and threat model. |
@@ -268,7 +268,57 @@ The DarkArts language is a formal notation used in annotations. It includes:
 
 ## Examples
 
-See the `examples/` directory for complete examples in Python and TypeScript.
+### Function with Invariants
+
+**Python**:
+```python
+def transfer_funds(from_account, to_account, amount):
+    """@voodocs
+    preconditions: [
+        "from_account.balance >= amount",
+        "amount > 0",
+        "from_account != to_account"
+    ]
+    postconditions: [
+        "from_account.balance = from_account.balance₀ - amount",
+        "to_account.balance = to_account.balance₀ + amount"
+    ]
+    invariants: [
+        "total_balance = from_account.balance + to_account.balance (conservation)",
+        "from_account.balance >= 0",
+        "to_account.balance >= 0"
+    ]
+    complexity: "O(1)"
+    """
+    from_account.balance -= amount
+    to_account.balance += amount
+```
+
+### Class with Invariants
+
+**Python**:
+```python
+class BankAccount:
+    """@voodocs
+    class_invariants: [
+        "balance >= 0 (no overdrafts)",
+        "account_id is unique and immutable"
+    ]
+    """
+    
+    def deposit(self, amount):
+        """@voodocs
+        preconditions: ["amount > 0"]
+        postconditions: ["self.balance = self.balance₀ + amount"]
+        invariants: [
+            "self.balance >= 0 (class invariant maintained)",
+            "self.account_id unchanged"
+        ]
+        """
+        self.balance += amount
+```
+
+See the `examples/` directory for more complete examples in Python and TypeScript.
 
 ---
 

package/cli.py

@@ -137,7 +137,7 @@ Documentation: https://github.com/3vilEnterprises/vooodooo-magic/tree/main/packa
     parser.add_argument(
         "--version",
         action="version",
-        version="VooDocs 0.1.1"
+        version="VooDocs 0.1.2"
     )
     
     subparsers = parser.add_subparsers(dest="command", help="Available commands")
@@ -435,7 +435,7 @@ def cmd_init(args):
         config = {
             "project_name": project_name,
             "language": language,
-            "version": "0.1.1",
+            "version": "0.1.2",
             "output_dir": "./voodocs-output",
             "test_framework": "pytest",
             "api_format": "openapi",

package/examples/test_function_invariants.py

@@ -0,0 +1,134 @@
+"""
+Example demonstrating function-level invariants in VooDocs.
+
+This file shows how to use invariants at the function level to document
+properties that must hold throughout the function's execution.
+"""
+
+
+def transfer_funds(from_account, to_account, amount):
+    """@voodocs
+    preconditions: [
+        "from_account.balance >= amount",
+        "amount > 0",
+        "from_account != to_account"
+    ]
+    postconditions: [
+        "from_account.balance = from_account.balance₀ - amount",
+        "to_account.balance = to_account.balance₀ + amount",
+        "total_balance = from_account.balance + to_account.balance = total_balance₀"
+    ]
+    invariants: [
+        "total_balance = from_account.balance + to_account.balance (conservation of funds)",
+        "from_account.balance >= 0 (no negative balances)",
+        "to_account.balance >= 0 (no negative balances)",
+        "amount remains constant throughout execution"
+    ]
+    side_effects: [
+        "Modifies from_account.balance",
+        "Modifies to_account.balance",
+        "Logs transaction to audit trail"
+    ]
+    complexity: "O(1)"
+    """
+    # Verify preconditions
+    if from_account.balance < amount:
+        raise ValueError("Insufficient funds")
+    if amount <= 0:
+        raise ValueError("Amount must be positive")
+    if from_account == to_account:
+        raise ValueError("Cannot transfer to same account")
+    
+    # Perform transfer (invariants hold throughout)
+    from_account.balance -= amount
+    to_account.balance += amount
+    
+    # Log transaction
+    print(f"Transferred {amount} from {from_account.id} to {to_account.id}")
+
+
+def binary_search(arr, target):
+    """@voodocs
+    preconditions: [
+        "arr is sorted in ascending order",
+        "∀ i, j: 0 ≤ i < j < len(arr) ⇒ arr[i] ≤ arr[j]"
+    ]
+    postconditions: [
+        "result ≥ 0 ⇒ arr[result] = target",
+        "result = -1 ⇒ target ∉ arr"
+    ]
+    invariants: [
+        "0 ≤ left ≤ right < len(arr) (search bounds)",
+        "target ∈ arr ⇒ target ∈ arr[left:right+1] (target in search range)",
+        "arr remains unchanged (no side effects on input)"
+    ]
+    complexity: "O(log n) where n = len(arr)"
+    """
+    left, right = 0, len(arr) - 1
+    
+    while left <= right:
+        mid = (left + right) // 2
+        
+        if arr[mid] == target:
+            return mid
+        elif arr[mid] < target:
+            left = mid + 1
+        else:
+            right = mid - 1
+    
+    return -1
+
+
+class BankAccount:
+    """@voodocs
+    class_invariants: [
+        "balance >= 0 (no overdrafts)",
+        "account_id is unique and immutable",
+        "len(transaction_history) >= 0"
+    ]
+    """
+    
+    def __init__(self, account_id, initial_balance=0):
+        """@voodocs
+        preconditions: [
+            "initial_balance >= 0",
+            "account_id is not None"
+        ]
+        postconditions: [
+            "self.balance = initial_balance",
+            "self.account_id = account_id",
+            "len(self.transaction_history) = 0"
+        ]
+        invariants: [
+            "self.balance >= 0 (established at initialization)"
+        ]
+        """
+        self.account_id = account_id
+        self.balance = initial_balance
+        self.transaction_history = []
+    
+    def deposit(self, amount):
+        """@voodocs
+        preconditions: [
+            "amount > 0"
+        ]
+        postconditions: [
+            "self.balance = self.balance₀ + amount",
+            "len(self.transaction_history) = len(self.transaction_history₀) + 1"
+        ]
+        invariants: [
+            "self.balance >= 0 (class invariant maintained)",
+            "amount remains constant",
+            "self.account_id unchanged"
+        ]
+        side_effects: [
+            "Modifies self.balance",
+            "Appends to self.transaction_history"
+        ]
+        complexity: "O(1)"
+        """
+        if amount <= 0:
+            raise ValueError("Deposit amount must be positive")
+        
+        self.balance += amount
+        self.transaction_history.append(("deposit", amount))

package/lib/darkarts/plugins/voodocs/documentation_generator.py

@@ -567,7 +567,7 @@ class DocumentationGenerator:
         
         # Documentation coverage badge
         total_items = len(parsed.module.classes) + len(parsed.get_all_functions())
-        annotated_items = sum(1 for _ in parsed.module.classes if _.invariants or _.state_transitions)
+        annotated_items = sum(1 for _ in parsed.module.classes if _.class_invariants or _.state_transitions)
         annotated_items += sum(1 for f in parsed.get_all_functions() if f.preconditions or f.postconditions)
         
         if total_items > 0:

package/lib/darkarts/telemetry.py

@@ -20,7 +20,7 @@ SUPABASE_URL = os.getenv("VOODOCS_SUPABASE_URL", "https://sjatkayudkbkmipubhfy.s
 SUPABASE_ANON_KEY = os.getenv("VOODOCS_SUPABASE_ANON_KEY", "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InNqYXRrYXl1ZGtia21pcHViaGZ5Iiwicm9sZSI6ImFub24iLCJpYXQiOjE3NjYxNjE0MTMsImV4cCI6MjA4MTczNzQxM30.Wj3dbokjKPsmWTgbPw77aPnCoZCsE5hrFfIH-R_ErzI")
 
 # VooDocs version
-VERSION = "0.1.1"
+VERSION = "0.1.2"
 
 class TelemetryClient:
     """Anonymous telemetry client for VooDocs CLI."""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voodocs/cli",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "AI-Native Documentation System - Generate docs, tests, and API specs from @voodocs annotations using the DarkArts language",
   "main": "cli.py",
   "bin": {