@voodocs/cli 3.0.4 → 3.0.6

package/lib/cli/__init__.py

@@ -16,7 +16,7 @@ This module provides the command-line interface for VooDocs.
 import click
 from typing import Optional
 
-__version__ = "3.0.4"
+__version__ = "3.0.6"
 
 
 @click.group()

package/lib/darkarts/annotations/parser.py

@@ -920,10 +920,13 @@ class AnnotationParser:
     
     def _overlay_annotations(self, structure: ParsedAnnotations, annotations_by_line: Dict[int, Any]) -> ParsedAnnotations:
         """Overlay parsed annotations onto code structure by matching line numbers."""
+        # Find the first code element line number
+        first_code_line = self._get_first_code_line(structure)
+        
         # Match annotations to code elements by finding the closest following element
         for line_num, annotation in annotations_by_line.items():
             # Check if this is a module-level annotation (appears before any code)
-            if self._is_module_annotation(annotation):
+            if self._is_module_annotation(annotation, line_num, first_code_line):
                 self._apply_module_annotation_from_darkarts(structure.module, annotation)
                 continue
             
@@ -959,9 +962,31 @@ class AnnotationParser:
         
         return structure
     
-    def _is_module_annotation(self, annotation: Any) -> bool:
-        """Check if annotation is module-level."""
-        return hasattr(annotation, 'module') and annotation.module
+    def _get_first_code_line(self, structure: ParsedAnnotations) -> int:
+        """Get the line number of the first code element (function or class)."""
+        min_line = float('inf')
+        
+        # Check all functions
+        for func in structure.module.functions:
+            if func.line_number > 0 and func.line_number < min_line:
+                min_line = func.line_number
+        
+        # Check all classes
+        for cls in structure.module.classes:
+            if cls.line_number > 0 and cls.line_number < min_line:
+                min_line = cls.line_number
+        
+        return min_line if min_line != float('inf') else 999999
+    
+    def _is_module_annotation(self, annotation: Any, line_num: int, first_code_line: int) -> bool:
+        """Check if annotation is module-level (has ⊢{} and appears before first code element)."""
+        # Must have module purpose (⊢{})
+        if not (hasattr(annotation, 'module') and annotation.module):
+            return False
+        
+        # Must appear before the first function/class
+        # Allow up to 5 lines before first code element for module annotation
+        return line_num < first_code_line
     
     def _apply_module_annotation_from_darkarts(self, module: ModuleAnnotation, annotation: Any):
         """Apply @darkarts annotation to module."""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voodocs/cli",
-  "version": "3.0.4",
+  "version": "3.0.6",
   "description": "AI-Native Symbolic Documentation System - The world's first documentation tool using mathematical notation with semantic validation",
   "main": "voodocs_cli.py",
   "bin": {

package/templates/PROJECT.darkarts.md

@@ -1,75 +1,112 @@
 # Project-Level DarkArts Annotations
 
-This file contains project-wide annotations that apply to the entire codebase.
+# @darkarts
+# ⊢{distributed microservices platform}
+# ⊨{∀service→isolated-db, ∀api→authenticated, ∀transaction→idempotent}
+# ⊣{postgres≥14, redis≥7, kubernetes≥1.24}
+# ⚠{kubernetes≥1.24, postgres≥14, redis≥7.0, node≥18}
 
-## Usage
+## About This File
+
+This file contains **project-wide annotations** that apply to the entire codebase.
 
 Place this file in your project root as `PROJECT.darkarts.md` and it will be automatically detected by `voodocs context generate`.
 
-## Syntax
+## How to Use
 
-Use standard @darkarts symbolic notation:
+**Important:** Annotations must use Python comment syntax (`#`) at the start of each line, not markdown code blocks.
 
+### Correct Format:
 ```
-@darkarts
-⊢{project purpose}
-⊨{global invariants}
-⊣{system-wide assumptions}
-⚠{technology requirements}
+# @darkarts
+# ⊢{your project purpose}
+# ⊨{global invariant 1, global invariant 2}
+# ⊣{assumption 1, assumption 2}
+# ⚠{requirement 1, requirement 2}
 ```
 
----
-
-## Example: Project-Level Annotations
-
+### Incorrect Format (won't work):
 ```markdown
 @darkarts
-⊢{distributed microservices platform for AI-powered financial services}
-
-⊨{
-  ∀service→isolated-db,
-  ∀api→authenticated,
-  ∀transaction→idempotent,
-  ∀data→encrypted-at-rest,
-  consistency:eventual
-}
-
-⊣{
-  postgres≥14 available,
-  redis cluster available,
-  kubernetes cluster available,
-  all services use UTC timestamps,
-  all APIs use JSON
-}
-
-⚠{
-  kubernetes≥1.24,
-  postgres≥14,
-  redis≥7.0,
-  node≥18,
-  python≥3.11
-}
+⊢{your project purpose}
 ```
 
----
+## Symbolic Notation Reference
+
+- `⊢{}` - Project purpose/description
+- `⊨{}` - Global invariants (system-wide rules that must always hold)
+- `⊣{}` - System-wide assumptions (what the system depends on)
+- `⚠{}` - Technology requirements (versions, dependencies)
+- `∂{}` - Dependencies (external systems, services)
+
+## Example: Real Project Annotations
+
+```
+# @darkarts
+# ⊢{3NS: Decentralized naming system with dual-layer resolution (on-chain + off-chain cache)}
+# 
+# ⊨{
+#   UUTRegister contract is source of truth,
+#   PostgreSQL is cache only,
+#   All database access enforced by Supabase RLS,
+#   3Pay is generic infrastructure - no domain logic,
+#   All domain-specific logic in plugins
+# }
+# 
+# ⊣{
+#   Supabase RLS policies enforce all access,
+#   PostgreSQL cache can be rebuilt from blockchain,
+#   UUTRegister contract is immutable,
+#   All services use UTC timestamps
+# }
+# 
+# ⚠{
+#   supabase-js≥2.0,
+#   postgres≥14,
+#   node≥18,
+#   typescript≥5.0
+# }
+```
 
 ## Architecture Decisions
 
-You can also document architecture decisions in plain Markdown:
+You can also document architecture decisions in plain Markdown below the annotations:
 
-### Decision: Event-Driven Architecture
+### Decision: Separated 3Pay as Generic Infrastructure (PRINCIPLE_6)
 
-**Rationale:** Enables loose coupling between services and supports eventual consistency model.
+**Date:** 2024-12
 
-**Alternatives Considered:**
-- Synchronous REST APIs (rejected: tight coupling, cascading failures)
-- GraphQL federation (rejected: complexity overhead)
+**Rationale:** 3Pay should be reusable across different domain systems, not tied to 3NS-specific logic.
+
+**What Changed:**
+- Moved all domain-specific logic to plugins
+- 3Pay now handles only: payments, subscriptions, credits
+- Domain resolution logic stays in 3NS
 
 **Trade-offs:**
-- ✅ Better scalability and resilience
-- ✅ Easier to add new services
-- ❌ More complex debugging
-- ❌ Requires event schema management
+- ✅ 3Pay can be reused for other projects
+- ✅ Cleaner separation of concerns
+- ❌ Slightly more complex plugin system
+
+---
+
+### Decision: PostgreSQL as Cache, UUTRegister as Source of Truth
+
+**Date:** 2024-11
+
+**Rationale:** Blockchain data is immutable and authoritative; PostgreSQL provides fast queries.
+
+**Implementation:**
+- UUTRegister contract stores all domain registrations
+- PostgreSQL caches data for fast lookups
+- Cache can be rebuilt from blockchain at any time
+- Supabase RLS enforces access control
+
+**Trade-offs:**
+- ✅ Fast queries via PostgreSQL
+- ✅ Authoritative data on blockchain
+- ✅ Can rebuild cache if corrupted
+- ❌ Requires cache synchronization logic
 
 ---
 
@@ -77,11 +114,11 @@ You can also document architecture decisions in plain Markdown:
 
 Document system-wide invariants that must hold across all services:
 
-- All user data must be encrypted at rest
-- All API endpoints must require authentication
-- All database transactions must be idempotent
-- All timestamps must use UTC
-- All monetary amounts must use decimal types (never float)
+- **Database Access:** All database access must go through Supabase RLS (no direct PostgreSQL access)
+- **Source of Truth:** UUTRegister contract is the only source of truth for domain ownership
+- **Cache Consistency:** PostgreSQL cache must be rebuildable from blockchain
+- **Generic Infrastructure:** 3Pay must remain generic (no domain-specific logic)
+- **Plugin Isolation:** All domain-specific logic must be in plugins, not core
 
 ---
 
@@ -89,23 +126,25 @@ Document system-wide invariants that must hold across all services:
 
 Document assumptions that the entire system relies on:
 
-- PostgreSQL is always available (99.9% SLA)
-- Redis is used only for caching (not source of truth)
-- All services can communicate via internal network
-- Clock skew between services is < 1 second
-- All services use the same authentication service
+- **Supabase RLS:** RLS policies correctly enforce all access control
+- **Blockchain Availability:** UUTRegister contract is always accessible
+- **Cache Rebuild:** PostgreSQL can be rebuilt from blockchain if needed
+- **UTC Timestamps:** All services use UTC for timestamps
+- **Immutable Contracts:** Smart contracts are immutable after deployment
 
 ---
 
 ## Technology Stack
 
-Document the standard technology stack for the project:
-
 **Backend:**
 - Node.js 18+ (TypeScript)
-- Python 3.11+ (FastAPI)
-- PostgreSQL 14+
-- Redis 7.0+
+- Supabase (PostgreSQL + Auth + RLS)
+- Web3.js / Ethers.js (blockchain interaction)
+
+**Smart Contracts:**
+- Solidity 0.8+
+- Hardhat (development)
+- UUTRegister (domain registry)
 
 **Frontend:**
 - React 18+
@@ -113,16 +152,18 @@ Document the standard technology stack for the project:
 - TailwindCSS 3+
 
 **Infrastructure:**
-- Kubernetes 1.24+
-- Docker
-- GitHub Actions (CI/CD)
+- Supabase (hosted PostgreSQL)
+- Vercel / Netlify (frontend hosting)
+- Ethereum / Polygon (blockchain)
 
 ---
 
 ## Notes
 
-- This file is parsed by `voodocs context generate`
-- Annotations in this file are added to the `.voodocs.context` file
-- Global invariants from this file appear in the "Global Invariants" section
-- Architecture decisions can be written in plain Markdown
-- This file should be version controlled alongside your code
+- ✅ This file is parsed by `voodocs context generate`
+- ✅ Annotations must use `#` comment syntax (Python style)
+- ✅ Global invariants from this file appear in `.voodocs.context`
+- ✅ Architecture decisions can be written in plain Markdown
+- ✅ This file should be version controlled alongside your code
+- ❌ Don't use markdown code blocks for annotations (won't be parsed)
+- ❌ Don't forget the `#` at the start of each annotation line