@voodocs/cli 3.0.1 → 3.0.2

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.1"
+__version__ = "3.0.2"
 
 
 @click.group()

package/lib/cli/generate.py

@@ -110,6 +110,47 @@ def generate(
         click.echo(f"Recursive: {click.style('Yes', fg='green')}")
     click.echo()
     
+    # Default exclusion patterns
+    DEFAULT_EXCLUDE_PATTERNS = [
+        '**/node_modules/**',
+        '**/venv/**',
+        '**/.venv/**',
+        '**/env/**',
+        '**/.env/**',
+        '**/virtualenv/**',
+        '**/__pycache__/**',
+        '**/.git/**',
+        '**/.svn/**',
+        '**/.hg/**',
+        '**/dist/**',
+        '**/build/**',
+        '**/.next/**',
+        '**/.nuxt/**',
+        '**/coverage/**',
+        '**/.pytest_cache/**',
+        '**/.mypy_cache/**',
+        '**/.tox/**',
+        '**/site-packages/**',
+    ]
+    
+    def should_exclude(file_path: Path, exclude_patterns: List[str]) -> bool:
+        """Check if file should be excluded based on patterns."""
+        file_str = str(file_path)
+        for pattern in exclude_patterns:
+            # Convert glob pattern to simple string matching
+            # Handle ** patterns
+            pattern_parts = pattern.split('**')
+            if len(pattern_parts) > 1:
+                # Pattern contains **, check if any part matches
+                for part in pattern_parts:
+                    if part and part.strip('/') in file_str:
+                        return True
+            else:
+                # Simple pattern matching
+                if pattern.strip('*').strip('/') in file_str:
+                    return True
+        return False
+    
     # Collect source files
     source_path = Path(source)
     files_to_process: List[Path] = []
@@ -123,7 +164,10 @@ def generate(
         
         if recursive:
             for ext in extensions:
-                files_to_process.extend([f for f in source_path.glob(f"**/{ext}") if f.is_file()])
+                all_files = source_path.glob(f"**/{ext}")
+                # Filter out excluded paths
+                filtered_files = [f for f in all_files if f.is_file() and not should_exclude(f, DEFAULT_EXCLUDE_PATTERNS)]
+                files_to_process.extend(filtered_files)
         else:
             for ext in extensions:
                 files_to_process.extend([f for f in source_path.glob(ext) if f.is_file()])

package/lib/darkarts/context/commands.py

@@ -1214,19 +1214,44 @@ def cmd_context_generate(source_dir: Optional[str] = None, update_existing: bool
         sys.path.insert(0, str(Path(__file__).parent.parent))
         from annotations.parser import AnnotationParser
         
-        # Scan for annotations
+        # Initialize parser
         parser = AnnotationParser()
+        
+        # Check for PROJECT.darkarts.md file
+        project_file = scan_path / 'PROJECT.darkarts.md'
+        project_annotations = None
+        if project_file.exists():
+            info(f"Found PROJECT.darkarts.md")
+            try:
+                project_annotations = parser.parse_file(str(project_file))
+            except Exception as e:
+                warning(f"Failed to parse PROJECT.darkarts.md: {e}")
+        
+        # Scan for annotations
         results = parser.parse_directory(scan_path)
         
-        if not results:
+        if not results and not project_annotations:
             warning("No @darkarts annotations found.")
-            info("Add @darkarts annotations to your code first.")
+            info("Add @darkarts annotations to your code or create PROJECT.darkarts.md")
             return 1
         
         # Extract global invariants from all annotations
         global_invariants = set()
         assumptions = []
         
+        # Process PROJECT.darkarts.md if it exists
+        if project_annotations:
+            module_ann = project_annotations.module
+            if hasattr(module_ann, 'invariants') and module_ann.invariants:
+                for inv in module_ann.invariants:
+                    global_invariants.add(inv)
+            if hasattr(module_ann, 'assumptions') and module_ann.assumptions:
+                for assumption in module_ann.assumptions:
+                    assumptions.append({
+                        'description': assumption,
+                        'source': 'PROJECT.darkarts.md'
+                    })
+        
         # Extract modules using helper function
         modules_info = extract_modules_from_results(results, scan_path)
         

package/lib/darkarts/context/yaml_utils.py

@@ -423,6 +423,46 @@ def format_context_as_markdown(context: ContextFile) -> str:
         lines.append("---")
         lines.append("")
     
+    # Modules
+    if context.architecture.modules:
+        lines.append("## 📦 Modules")
+        lines.append("")
+        lines.append(f"Total modules: {len(context.architecture.modules)}")
+        lines.append("")
+        for name, module in context.architecture.modules.items():
+            lines.append(f"### {name}")
+            lines.append("")
+            if module.description:
+                lines.append(f"**Description:** {module.description}")
+                lines.append("")
+            if module.dependencies:
+                lines.append(f"**Dependencies:** {', '.join(module.dependencies)}")
+                lines.append("")
+            if module.assumptions:
+                lines.append("**Assumptions:**")
+                for assumption in module.assumptions:
+                    lines.append(f"- {assumption}")
+                lines.append("")
+            if module.invariants:
+                lines.append("**Invariants:**")
+                for invariant in module.invariants:
+                    lines.append(f"- {invariant}")
+                lines.append("")
+        lines.append("---")
+        lines.append("")
+    
+    # Assumptions
+    if context.assumptions:
+        lines.append("## ⚠️ Assumptions")
+        lines.append("")
+        lines.append(f"Total assumptions: {len(context.assumptions)}")
+        lines.append("")
+        for assumption in context.assumptions:
+            lines.append(f"- {assumption}")
+        lines.append("")
+        lines.append("---")
+        lines.append("")
+    
     # Known Issues
     if context.known_issues:
         lines.append("## ⚠️ Known Issues")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voodocs/cli",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "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

@@ -0,0 +1,128 @@
+# Project-Level DarkArts Annotations
+
+This file contains project-wide annotations that apply to the entire codebase.
+
+## Usage
+
+Place this file in your project root as `PROJECT.darkarts.md` and it will be automatically detected by `voodocs context generate`.
+
+## Syntax
+
+Use standard @darkarts symbolic notation:
+
+```
+@darkarts
+⊢{project purpose}
+⊨{global invariants}
+⊣{system-wide assumptions}
+⚠{technology requirements}
+```
+
+---
+
+## Example: Project-Level Annotations
+
+```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
+}
+```
+
+---
+
+## Architecture Decisions
+
+You can also document architecture decisions in plain Markdown:
+
+### Decision: Event-Driven Architecture
+
+**Rationale:** Enables loose coupling between services and supports eventual consistency model.
+
+**Alternatives Considered:**
+- Synchronous REST APIs (rejected: tight coupling, cascading failures)
+- GraphQL federation (rejected: complexity overhead)
+
+**Trade-offs:**
+- ✅ Better scalability and resilience
+- ✅ Easier to add new services
+- ❌ More complex debugging
+- ❌ Requires event schema management
+
+---
+
+## Global Invariants
+
+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)
+
+---
+
+## System-Wide Assumptions
+
+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
+
+---
+
+## Technology Stack
+
+Document the standard technology stack for the project:
+
+**Backend:**
+- Node.js 18+ (TypeScript)
+- Python 3.11+ (FastAPI)
+- PostgreSQL 14+
+- Redis 7.0+
+
+**Frontend:**
+- React 18+
+- TypeScript 5+
+- TailwindCSS 3+
+
+**Infrastructure:**
+- Kubernetes 1.24+
+- Docker
+- GitHub Actions (CI/CD)
+
+---
+
+## 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