npm - @ngocsangairvds/vsaf - Versions diffs - 3.2.14 → 3.2.16 - Mend

@ngocsangairvds/vsaf 3.2.14 → 3.2.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1442) hide show

package/tools/vds-scripts/hexagonal_orchestrator/README.md DELETED Viewed

@@ -1,530 +0,0 @@
-# VDS Hexagonal Orchestrator
-A CLI tool for analyzing codebases for hexagonal/clean architecture compliance.
-## Overview
-The VDS Hexagonal Orchestrator validates that repositories follow hexagonal architecture (also known as clean architecture or ports & adapters pattern). It ensures:
-- Domain logic independence from frameworks, UI, and databases
-- Proper ports & adapters pattern implementation
-- Clear separation of concerns between layers
-- Dependency rule compliance (dependencies point inward)
-## Features
-- Multi-language support (Python, Java, TypeScript/JavaScript)
-- Configurable architecture rules
-- Detailed compliance reports
-- Clean JSON output for programmatic consumption
-- Integration with VDS audit workflows
-## Installation
-### Prerequisites
-- Python 3.11 or higher
-- uv package manager
-### Install from Source
-```bash
-# Navigate to vds-scripts directory
-cd WHO-project/vds-scripts
-# Install the package
-uv sync --package vds-hexagonal-orchestrator
-```
-### Optional Dependencies
-For Java analysis support:
-```bash
-uv sync --package vds-hexagonal-orchestrator --extra java
-```
-## Usage
-### Basic Analysis
-```bash
-# Analyze a repository
-./scripts/worktree_uv.sh run --project vds_cli vds-cli hexagonal analyze /path/to/repo
-# Analyze with specific language
-./scripts/worktree_uv.sh run --project vds_cli vds-cli hexagonal analyze /path/to/repo --language python
-# Generate detailed report
-./scripts/worktree_uv.sh run --project vds_cli vds-cli hexagonal analyze /path/to/repo --output report.md
-```
-### JSON Output
-The `--json-only` flag outputs ONLY valid, parseable JSON to stdout. All progress messages and informational output are sent to stderr, making it safe to pipe the output to other tools.
-```bash
-# Output only JSON to stdout (progress goes to stderr)
-./scripts/worktree_uv.sh run --project vds_cli vds-cli hexagonal /path/to/repo --json-only
-# Pipe JSON to other tools
-./scripts/worktree_uv.sh run --project vds_cli vds-cli hexagonal /path/to/repo --json-only | jq '.compliance_level'
-# Parse JSON with Python
-./scripts/worktree_uv.sh run --project vds_cli vds-cli hexagonal /path/to/repo --json-only | python3 -c "import json, sys; data = json.load(sys.stdin); print(data['total_violations'])"
-# Save JSON to file
-./scripts/worktree_uv.sh run --project vds_cli vds-cli hexagonal /path/to/repo --json-only --output report.json
-# Combine with filters
-./scripts/worktree_uv.sh run --project vds_cli vds-cli hexagonal /path/to/repo --json-only --layer domain --severity critical
-```
-**Note**: When using `--json-only`, the following behavior is guaranteed:
-- ✅ Stdout contains ONLY valid JSON (no extra text, no progress messages)
-- ✅ Progress messages like "Analyzing repository:" are sent to stderr
-- ✅ Error messages are sent to stderr
-- ✅ Safe for piping to JSON parsers (jq, python json module, etc.)
-### Configuration
-Create a `.hexagonal.yaml` file in your repository root to customize analysis:
-```yaml
-# Architecture layers configuration
-layers:
-  domain: ["src/domain", "src/core"]
-  application: ["src/application", "src/usecases"]
-  infrastructure: ["src/infrastructure", "src/adapters"]
-  presentation: ["src/presentation", "src/api"]
-# Rules to enforce
-rules:
-  enforce_dependency_direction: true
-  allow_infrastructure_in_domain: false
-# Output settings
-output:
-  format: markdown  # or json
-  include_violations: true
-  include_suggestions: true
-```
-### CLI Commands
-```bash
-# Show help
-./scripts/worktree_uv.sh run --project vds_cli vds-cli hexagonal --help
-# Analyze repository
-./scripts/worktree_uv.sh run --project vds_cli vds-cli hexagonal analyze [OPTIONS] REPO_PATH
-# Validate configuration
-./scripts/worktree_uv.sh run --project vds_cli vds-cli hexagonal validate-config [CONFIG_PATH]
-# Generate default configuration
-./scripts/worktree_uv.sh run --project vds_cli vds-cli hexagonal init-config
-```
-### Analysis Options
-```
-Options:
-  --language TEXT          Programming language (python, java, typescript)
-  --config PATH            Path to configuration file
-  --output PATH            Output file path for report
-  --format TEXT            Output format (markdown, json)
-  --json-only             Output only JSON to stdout (progress to stderr)
-  --verbose               Enable verbose logging
-  --cache-dir PATH        Custom cache directory location
-  --no-cache              Disable caching (re-analyze all files)
-  --help                  Show this message and exit
-```
-### Cache Management
-```bash
-# Disable caching for a single run
-./scripts/worktree_uv.sh run --project vds_cli vds-cli hexagonal /path/to/repo --no-cache
-# Use custom cache directory
-./scripts/worktree_uv.sh run --project vds_cli vds-cli hexagonal /path/to/repo --cache-dir /tmp/cache
-# In CI/CD, use repository-specific cache directories
-./scripts/worktree_uv.sh run --project vds_cli vds-cli hexagonal /path/to/repo \
-  --cache-dir "$CI_CACHE_DIR/hexagonal-$REPO_NAME"
-```
-## Architecture Validation
-The analyzer checks for:
-### Layer Violations
-- Domain layer importing from infrastructure
-- Domain layer importing from presentation
-- Application layer importing from infrastructure (outside of adapters)
-### Dependency Rule
-- All dependencies should point inward (toward the domain)
-- Infrastructure depends on application ports
-- Application depends on domain
-- Domain has no external dependencies
-### Ports & Adapters Pattern
-- Clear separation between ports (interfaces) and adapters (implementations)
-- Primary adapters (controllers, CLI) interact with application through ports
-- Secondary adapters (repositories, external services) implement application ports
-## Output
-The analyzer generates reports showing:
-1. **Compliance Score**: Overall architecture compliance percentage
-2. **Violations**: List of detected architecture violations
-3. **Suggestions**: Recommendations for fixing violations
-4. **Statistics**: Metrics about layer sizes and dependencies
-### Example Report
-```markdown
-# Hexagonal Architecture Compliance Report
-Repository: example-service
-Analysis Date: 2025-01-15 10:30:00
-## Summary
-- Compliance Score: 85%
-- Total Violations: 3
-- Critical Violations: 1
-- Warnings: 2
-## Violations
-### Critical
-1. **Domain Import Violation** (src/domain/entities/user.py:15)
-   - Domain layer imports from infrastructure
-   - Import: `from infrastructure.database import db`
-   - Suggestion: Use dependency injection or repository pattern
-### Warnings
-1. **Layer Boundary** (src/application/services/order_service.py:8)
-   - Application layer has tight coupling to infrastructure
-   - Consider using port/interface abstraction
-## Statistics
-- Domain Files: 12
-- Application Files: 24
-- Infrastructure Files: 18
-- Presentation Files: 8
-```
-### JSON Output Structure
-When using `--json-only`, the output structure is:
-```json
-{
-  "repository_path": "/path/to/repo",
-  "timestamp": "2025-01-15T10:30:00",
-  "files_scanned": 62,
-  "files_analyzed": 15,
-  "coverage_ratio": 0.24,
-  "compliance_level": 2.5,
-  "confidence_score": 0.85,
-  "total_violations": 3,
-  "violations_by_severity": {
-    "critical": 1,
-    "major": 1,
-    "minor": 1
-  },
-  "violations_by_layer": {
-    "domain": {
-      "critical": 1,
-      "major": 0,
-      "minor": 0
-    }
-  },
-  "layer_distribution": {
-    "python": 45,
-    "java": 17
-  },
-  "violations": [
-    {
-      "violation_id": "HEX-001",
-      "file_path": "src/domain/entities/user.py",
-      "line_number": 15,
-      "layer": "domain",
-      "severity": "critical",
-      "category": "Infrastructure import in domain",
-      "detection_mode": "python_ast",
-      "confidence": 0.95,
-      "code_snippet": "from infrastructure.database import db",
-      "remediation_steps": ["Remove infrastructure dependency"]
-    }
-  ]
-}
-```
-## Development
-### Running Tests
-The test suite uses pytest markers to separate fast unit tests from slower integration tests.
-#### Run All Tests
-```bash
-# Run all tests (unit + integration)
-uv run --project hexagonal_orchestrator pytest tests/
-```
-#### Run Only Fast Unit Tests
-For quick feedback during development:
-```bash
-# Run only unit tests (fast, isolated tests with mocks)
-uv run --project hexagonal_orchestrator pytest -m unit tests/
-# Expected runtime: < 2 seconds
-```
-#### Run Integration Tests
-```bash
-# Run integration tests (slower, test real functionality)
-uv run --project hexagonal_orchestrator pytest -m integration tests/
-# Expected runtime: ~14 seconds
-```
-#### Skip Slow Tests
-```bash
-# Skip tests marked as slow (>1s runtime)
-uv run --project hexagonal_orchestrator pytest -m "not slow" tests/
-```
-#### Run Fast Tests for Development
-```bash
-# Run unit tests excluding slow ones (fastest feedback loop)
-uv run --project hexagonal_orchestrator pytest -m "unit and not slow" tests/
-```
-#### List Available Markers
-```bash
-# Show all registered pytest markers
-uv run --project hexagonal_orchestrator pytest --markers | grep -E "(unit|integration|slow)"
-```
-### Test Markers Reference
-| Marker | Description | Typical Runtime |
-|--------|-------------|-----------------|
-| `unit` | Fast, isolated tests with mocks | < 0.1s each |
-| `integration` | Slower tests that test real functionality | 0.5-2s each |
-| `slow` | Tests that take >1s to run | > 1s each |
-### Test Files by Type
-**Unit Tests** (marked with `@pytest.mark.unit`):
-- `tests/test_cli_unit.py` - CLI unit tests using mocks
-- `tests/test_foundation.py` - Foundation module tests
-- `tests/test_java_analyzer.py` - Java analyzer tests
-- `tests/test_cache.py::TestCacheManager` - Cache unit tests
-**Integration Tests** (marked with `@pytest.mark.integration`):
-- `tests/test_cli_integration.py` - Full CLI integration tests
-- `tests/test_integration.py` - Full pipeline tests
-- `tests/test_cache.py::TestCacheIntegration` - Cache integration tests
-**Slow Tests** (marked with `@pytest.mark.slow`):
-- `tests/test_cli_integration.py` - Subprocess-based tests (~14s total)
-- `tests/test_integration.py::TestFullPipelineOnFixtures` - Full analysis tests
-### Testing Clean JSON Output
-```bash
-# Test that --json-only outputs clean JSON
-./scripts/worktree_uv.sh run --project vds_cli vds-cli hexagonal tests/fixtures/java-noncompliant --json-only | python3 -c "import json, sys; json.load(sys.stdin)"
-# Verify progress goes to stderr
-./scripts/worktree_uv.sh run --project vds_cli vds-cli hexagonal tests/fixtures/java-noncompliant --json-only 2>/dev/null | jq '.compliance_level'
-```
-### Code Quality
-```bash
-# Run linter
-uv run --project hexagonal_orchestrator ruff check src/
-# Format code
-uv run --project hexagonal_orchestrator ruff format src/
-```
-## Caching
-The hexagonal analyzer uses file-based caching to speed up re-analysis of unchanged files.
-### How Caching Works
-- **Cache Location**: `~/.cache/vds-hexagonal/hexagonal_cache.json` (OS-specific)
-  - macOS/Linux: `~/.cache/vds-hexagonal/`
-  - Windows: `~\AppData\Local\vds-hexagonal\`
-- **Cache Key Format**: `<repo_id>:<relative_path>`
-  - `repo_id`: First 12 characters of SHA256 hash of repository root path
-  - `relative_path`: File path relative to repository root
-- **Cache Invalidation**:
-  - File content hash changes (SHA256)
-  - Cache version mismatch (current version: 1.1)
-  - File deleted
-  - `--no-cache` flag used
-### Multi-Repository Support
-**Important**: The cache uses repository-specific keys to prevent cross-repository pollution.
-Each repository gets a unique `repo_id` based on its root path, ensuring:
-- Different repositories don't share cache entries
-- Files with identical paths in different repos are cached separately
-- Same-repo re-runs benefit from cached results
-Example cache key: `a1b2c3d4e5f6:src/domain/user.py`
-This was fixed in version 1.1 to address cache pollution when analyzing multiple repositories.
-### Cache Benefits
-- **Faster Re-analysis**: Unchanged files skip expensive AST parsing (80-95% hit rate for incremental changes)
-- **Incremental Analysis**: Only analyze modified files
-- **Persistent Across Runs**: Cache survives between CLI invocations
-- **Thread-Safe**: Concurrent analysis operations are safe
-### When to Use `--no-cache`
-- After significant codebase refactoring
-- When analyzing a repository for the first time after an analyzer upgrade
-- When cache corruption is suspected
-- In CI/CD pipelines where cache state is uncertain
-### Cache Performance Metrics
-Cache statistics are included in JSON output:
-```bash
-./scripts/worktree_uv.sh run --project vds_cli vds-cli hexagonal /path/to/repo --json-only | jq '{
-  cache_hits,
-  cache_misses,
-  cache_enabled
-}'
-```
-## Multi-Repository Best Practices
-When analyzing multiple repositories, follow these practices for optimal performance:
-### 1. Leverage Default Caching
-The cache automatically handles multiple repositories through unique `repo_id` prefixes:
-```bash
-# Analyze multiple repos - cache is isolated per repo
-./scripts/worktree_uv.sh run --project vds_cli vds-cli hexagonal /path/to/repo-a
-./scripts/worktree_uv.sh run --project vds_cli vds-cli hexagonal /path/to/repo-b
-```
-### 2. Use Separate Cache Directories for CI/CD
-In CI/CD environments, use repository-specific cache directories:
-```bash
-./scripts/worktree_uv.sh run --project vds_cli vds-cli hexagonal /path/to/repo \
-  --cache-dir "$CI_CACHE_DIR/hexagonal-$REPO_NAME"
-```
-### 3. Initial Analysis vs. Incremental
-- **First run**: No cache hits, all files analyzed (slower)
-- **Subsequent runs**: Only changed files re-analyzed (faster)
-- **Expected cache hit rate**: 80-95% for incremental changes
-### 4. Cache Location Awareness
-The cache is stored in a shared location by default and can grow large with many repositories. Consider:
-- Using `--cache-dir` for per-project cache isolation
-- Periodically clearing old cache entries (automatically recreated on version upgrades)
-- The cache file is recreated on version upgrades (e.g., 1.0 → 1.1)
-## Troubleshooting
-### Cache-Related Issues
-**Problem**: Cache not being used, all files re-analyzed every time
-**Solutions**:
-1. Verify caching is not disabled: Check that `--no-cache` flag is not set
-2. Check cache file permissions: Ensure `~/.cache/vds-hexagonal/` is writable
-3. Verify cache version: If you recently upgraded, old cache entries are invalidated automatically (version 1.0 → 1.1)
-4. Check file content: Cache uses content hash, not timestamps
-**Problem**: Different repositories showing each other's results
-**Solution**: This was fixed in cache version 1.1. Ensure you're using the latest version. The cache now uses `<repo_id>:<relative_path>` keys to isolate repositories.
-**Problem**: Cache file is corrupted
-**Solutions**:
-1. Use `--no-cache` to bypass and rebuild cache
-2. Manually delete cache file: `rm ~/.cache/vds-hexagonal/hexagonal_cache.json`
-3. The cache is automatically recreated on next run
-**Problem**: Cache consuming too much disk space
-**Solutions**:
-1. Use `--cache-dir` to split cache across projects
-2. Clear cache periodically: The cache is recreated on version upgrades
-3. Use `--no-cache` for one-off analyses that don't need caching
-### Performance Issues
-**Problem**: First analysis is slow
-**Explanation**: First analysis has zero cache hits and must parse all files. This is expected behavior. Subsequent runs will be faster.
-**Problem**: Cache hit rate is low despite unchanged files
-**Check**:
-1. Verify files are not being modified between runs (content hash matters, not timestamps)
-2. Check if repository path is stable (changing paths invalidate `repo_id`)
-3. Look for dynamic file generation that changes content
-### Multi-Repo Analysis Issues
-**Problem**: Analyzing multiple repos sequentially, second repo is very slow
-**Solutions**:
-1. This should not happen with cache version 1.1+ (each repo has unique namespace)
-2. If using older version, upgrade to get repo-specific cache keys
-3. As workaround, use `--cache-dir` for each repository
-## Integration with VDS Audit
-The hexagonal orchestrator integrates with the VDS audit workflow:
-```bash
-# Run as part of audit
-./scripts/worktree_uv.sh run --project vds_cli vds-cli audit workflow-project --project-storage-key <PROJECT_ID> --include-hexagonal-check
-```
-## License
-Internal VDS tool - All rights reserved
-## Support
-For issues and questions:
-- VDS Internal Documentation
-- VDS Development Team

package/tools/vds-scripts/hexagonal_orchestrator/pyproject.toml DELETED Viewed

@@ -1,48 +0,0 @@
-[build-system]
-requires = ["hatchling>=1.20.0"]
-build-backend = "hatchling.build"
-[project]
-name = "vds-hexagonal-orchestrator"
-version = "1.1.0"
-description = "VDS Hexagonal Architecture Compliance Analyzer"
-readme = "README.md"
-requires-python = ">=3.11"
-dependencies = [
-    "typer>=0.24.1",
-    "pydantic>=2.12.0",
-    "structlog>=25.5.0",
-    "rich>=14.3.0",
-    "pyyaml>=6.0.0",
-]
-[project.optional-dependencies]
-java = ["javalang>=0.13.0"]
-dev = [
-    "pytest>=9.0.2",
-    "ruff>=0.15.1",
-]
-[project.scripts]
-vds-hexagonal = "vds_hexagonal_orchestrator.cli:main"
-[tool.hatch.build.targets.wheel]
-packages = ["src/vds_hexagonal_orchestrator"]
-[tool.pytest.ini_options]
-testpaths = ["tests"]
-markers = [
-    "unit: Fast, isolated tests with mocks",
-    "integration: Slower tests that test real functionality",
-    "slow: Tests that take >1s to run",
-]
-[tool.ruff]
-line-length = 120
-target-version = "py311"
-[tool.ruff.lint]
-# Intentional non-compliant fixture — tests analyze it for syntax violations
-per-file-ignores = { "*/tests/fixtures/python-noncompliant/**" = ["ALL"] }
-select = ["E", "F", "I", "W", "B", "C4", "UP"]
-ignore = ["E501", "B008"]

package/tools/vds-scripts/hexagonal_orchestrator/src/vds_hexagonal_orchestrator/__init__.py DELETED Viewed

@@ -1,39 +0,0 @@
-#!/usr/bin/env python3
-"""
-Hexagonal Architecture Compliance Orchestrator
-This package provides modular analysis of hexagonal architecture compliance
-for VDS repositories.
-"""
-from vds_hexagonal_orchestrator.classifier import LayerClassifier
-from vds_hexagonal_orchestrator.config import ConfigManager
-from vds_hexagonal_orchestrator.models import (
-    AnalyzerResult,
-    ComplianceReport,
-    DetectionMode,
-    LayerAssignment,
-    LayerName,
-    RepositoryProfile,
-    Violation,
-)
-from vds_hexagonal_orchestrator.profiler import RepositoryProfiler
-__version__ = "1.0.0"
-__all__ = [
-    # Version
-    "__version__",
-    # Models
-    "LayerAssignment",
-    "Violation",
-    "ComplianceReport",
-    "RepositoryProfile",
-    "AnalyzerResult",
-    "LayerName",
-    "DetectionMode",
-    # Core components
-    "RepositoryProfiler",
-    "LayerClassifier",
-    "ConfigManager",
-]

package/tools/vds-scripts/hexagonal_orchestrator/src/vds_hexagonal_orchestrator/analyzers/__init__.py DELETED Viewed

@@ -1,19 +0,0 @@
-#!/usr/bin/env python3
-"""
-Language analyzers for hexagonal compliance checking.
-This package contains pluggable analyzers for different programming languages.
-"""
-from vds_hexagonal_orchestrator.analyzers.base import AnalyzerPlugin, BaseAnalyzer
-from vds_hexagonal_orchestrator.analyzers.fallback import FallbackAnalyzer
-from vds_hexagonal_orchestrator.analyzers.java import JavaAstAnalyzer
-from vds_hexagonal_orchestrator.analyzers.python import PythonAstAnalyzer
-__all__ = [
-    "AnalyzerPlugin",
-    "BaseAnalyzer",
-    "JavaAstAnalyzer",
-    "PythonAstAnalyzer",
-    "FallbackAnalyzer",
-]