@vee-stack/delta-cli 2.0.4 → 2.0.6

package/dist/packages/domain/src/constitution/maintainability/ts.rules.js

@@ -0,0 +1,344 @@
+/**
+ * Delta Constitution - Maintainability Rules
+ * @description Code quality, testing, and documentation standards
+ * @version 1.0.0
+ * @see docs/architecture/CONSTITUTION.md
+ */
+// =============================================================================
+// MAINTAINABILITY RULE DEFINITIONS
+// =============================================================================
+export const MaintainabilityRules = {
+    version: '1.0.0',
+    lastUpdated: '2026-02-10',
+    // ============================================================================
+    // 1. LOCALITY OF BEHAVIOR
+    // ============================================================================
+    localityOfBehavior: {
+        enabled: true,
+        required: true,
+        description: 'All related code in one place',
+        principle: 'Co-location reduces cognitive load',
+        requirements: {
+            features: {
+                location: 'src/features/[name]/',
+                contains: ['UI', 'hooks', 'services', 'tests'],
+                maxDepth: 3,
+            },
+            modules: {
+                location: 'src/modules/[name]/',
+                contains: ['business logic', 'policies', 'types'],
+                maxDepth: 2,
+            },
+            core: {
+                location: 'src/core/[name]/',
+                contains: ['pure functions', 'domain logic'],
+                maxDepth: 2,
+            },
+        },
+        rules: [
+            {
+                id: 'MAINT-LOB-001',
+                name: 'No Deep Nesting',
+                description: 'Maximum 3 levels of directory nesting',
+                severity: 'warning',
+            },
+            {
+                id: 'MAINT-LOB-002',
+                name: 'Related Files Together',
+                description: 'Tests, types, and implementation in same directory',
+                severity: 'error',
+            },
+        ],
+    },
+    // ============================================================================
+    // 2. TESTING REQUIREMENTS
+    // ============================================================================
+    testing: {
+        enabled: true,
+        required: true,
+        description: 'Comprehensive test coverage',
+        coverage: {
+            unit: {
+                target: 80,
+                minimum: 70,
+                scope: 'functions, hooks, utilities',
+            },
+            integration: {
+                target: 60,
+                minimum: 50,
+                scope: 'modules, services',
+            },
+            e2e: {
+                target: 30,
+                minimum: 20,
+                scope: 'critical user flows',
+            },
+        },
+        types: {
+            unit: {
+                description: 'Test individual functions in isolation',
+                location: '__tests__/ or *.test.ts',
+                tools: ['vitest', 'jest'],
+            },
+            integration: {
+                description: 'Test module interactions',
+                location: '__tests__/integration/',
+                tools: ['vitest', 'supertest'],
+            },
+            constitution: {
+                description: 'Test architecture compliance',
+                location: 'tests/constitution/',
+                checks: ['import boundaries', 'pure functions', 'policy usage'],
+            },
+        },
+        rules: [
+            {
+                id: 'MAINT-TEST-001',
+                name: 'Test Pure Functions',
+                description: 'All pure functions must have unit tests',
+                severity: 'error',
+            },
+            {
+                id: 'MAINT-TEST-002',
+                name: 'Test Business Logic',
+                description: 'All business logic in modules must have tests',
+                severity: 'error',
+            },
+            {
+                id: 'MAINT-TEST-003',
+                name: 'Mock External Dependencies',
+                description: 'External services must be mocked in tests',
+                severity: 'warning',
+            },
+        ],
+    },
+    // ============================================================================
+    // 3. DOCUMENTATION
+    // ============================================================================
+    documentation: {
+        enabled: true,
+        required: true,
+        description: 'Documentation for every layer',
+        requirements: {
+            code: {
+                jsdoc: true,
+                description: 'Every exported function must have JSDoc',
+                required: ['description', 'param', 'returns'],
+            },
+            features: {
+                readme: 'README.md',
+                blueprint: 'docs/blueprints/[feature].md',
+                content: ['purpose', 'usage', 'api', 'examples'],
+            },
+            modules: {
+                readme: 'README.md',
+                content: ['purpose', 'public api', 'policies', 'examples'],
+            },
+            architecture: {
+                location: 'docs/architecture/',
+                files: [
+                    'CONSTITUTION.md',
+                    'OVERVIEW.md',
+                    'ENTERPRISE_ARCHITECTURE.md',
+                    'FEATURE_ASSESSMENT_TEMPLATE.md',
+                ],
+            },
+        },
+        rules: [
+            {
+                id: 'MAINT-DOC-001',
+                name: 'JSDoc Required',
+                description: 'All public exports must have JSDoc comments',
+                severity: 'error',
+            },
+            {
+                id: 'MAINT-DOC-002',
+                name: 'Feature Blueprint',
+                description: 'Each feature must have a blueprint document',
+                severity: 'warning',
+            },
+        ],
+    },
+    // ============================================================================
+    // 4. PURE FUNCTIONS
+    // ============================================================================
+    pureFunctions: {
+        enabled: true,
+        required: true,
+        description: 'Core must use pure functions only',
+        definition: {
+            deterministic: 'Same input always produces same output',
+            noSideEffects: 'No mutation of external state',
+            noDependencies: 'No reliance on external state',
+        },
+        rules: [
+            {
+                id: 'MAINT-PURE-001',
+                name: 'Core Functions Pure',
+                description: 'All functions in src/core/ must be pure',
+                severity: 'error',
+                check: 'AST analysis for side effects',
+            },
+            {
+                id: 'MAINT-PURE-002',
+                name: 'No Global State',
+                description: 'No global variables or singletons in Core',
+                severity: 'error',
+                forbidden: ['let global', 'var global', 'static state'],
+            },
+        ],
+        benefits: {
+            testing: 'Easy to test without mocks',
+            caching: 'Results can be safely cached',
+            concurrency: 'Safe to run in parallel',
+            debugging: 'Predictable behavior',
+        },
+    },
+    // ============================================================================
+    // 5. CODE QUALITY
+    // ============================================================================
+    codeQuality: {
+        enabled: true,
+        required: true,
+        description: 'Code quality standards',
+        metrics: {
+            complexity: {
+                cyclomatic: { max: 10, target: 5 },
+                cognitive: { max: 15, target: 10 },
+            },
+            lines: {
+                function: { max: 50, target: 30 },
+                file: { max: 300, target: 200 },
+            },
+            duplication: {
+                threshold: '5%',
+                target: '0%',
+            },
+        },
+        linting: {
+            eslint: {
+                config: '.eslintrc.cjs',
+                extends: ['next', 'typescript', 'prettier'],
+                customRules: 'constitution rules',
+            },
+            prettier: {
+                config: '.prettierrc',
+                enabled: true,
+            },
+        },
+        rules: [
+            {
+                id: 'MAINT-QUAL-001',
+                name: 'Max Complexity',
+                description: 'Cyclomatic complexity <= 10',
+                severity: 'warning',
+            },
+            {
+                id: 'MAINT-QUAL-002',
+                name: 'Max Function Length',
+                description: 'Functions should be <= 50 lines',
+                severity: 'warning',
+            },
+            {
+                id: 'MAINT-QUAL-003',
+                name: 'No Code Duplication',
+                description: 'Duplication <= 5%',
+                severity: 'error',
+            },
+        ],
+    },
+    // ============================================================================
+    // 6. NAMING CONVENTIONS
+    // ============================================================================
+    namingConventions: {
+        enabled: true,
+        required: true,
+        description: 'Consistent naming across the codebase',
+        conventions: {
+            files: {
+                components: 'PascalCase.tsx',
+                hooks: 'camelCase.ts (use*.ts)',
+                services: 'camelCase.service.ts',
+                utilities: 'camelCase.ts',
+                types: 'PascalCase.ts',
+                constants: 'UPPER_SNAKE_CASE.ts',
+            },
+            directories: {
+                features: 'kebab-case/',
+                modules: 'kebab-case/',
+                components: 'kebab-case/',
+            },
+            exports: {
+                functions: 'camelCase',
+                components: 'PascalCase',
+                types: 'PascalCase',
+                constants: 'UPPER_SNAKE_CASE',
+            },
+        },
+        rules: [
+            {
+                id: 'MAINT-NAME-001',
+                name: 'Descriptive Names',
+                description: 'Names should clearly describe purpose',
+                examples: {
+                    bad: ['x', 'data', 'process'],
+                    good: ['fileUploadProgress', 'analysisResult', 'validateUserInput'],
+                },
+            },
+        ],
+    },
+};
+export function validateTestCoverage(coverage) {
+    const violations = [];
+    let score = 100;
+    const { testing } = MaintainabilityRules;
+    if (coverage.unit < testing.coverage.unit.minimum) {
+        violations.push(`MAINT-TEST-COV: Unit coverage ${coverage.unit}% below minimum ${testing.coverage.unit.minimum}%`);
+        score -= 25;
+    }
+    if (coverage.integration < testing.coverage.integration.minimum) {
+        violations.push(`MAINT-TEST-COV: Integration coverage ${coverage.integration}% below minimum ${testing.coverage.integration.minimum}%`);
+        score -= 20;
+    }
+    if (coverage.e2e < testing.coverage.e2e.minimum) {
+        violations.push(`MAINT-TEST-COV: E2E coverage ${coverage.e2e}% below minimum ${testing.coverage.e2e.minimum}%`);
+        score -= 15;
+    }
+    return {
+        valid: violations.length === 0,
+        violations,
+        score: Math.max(0, score),
+    };
+}
+export function calculateMaintainabilityScore(checks) {
+    const maxScore = 100;
+    let score = 0;
+    // Testing (40 points)
+    if (checks.hasUnitTests)
+        score += 15;
+    if (checks.hasIntegrationTests)
+        score += 15;
+    if (checks.hasConstitutionTests)
+        score += 10;
+    // Documentation (25 points)
+    if (checks.hasJSDoc)
+        score += 10;
+    if (checks.hasReadme)
+        score += 10;
+    if (checks.hasBlueprints)
+        score += 5;
+    // Pure functions (20 points)
+    if (checks.coreUsesPureFunctions)
+        score += 20;
+    // Code quality (15 points)
+    if (checks.hasLinting)
+        score += 5;
+    if (checks.hasFormatting)
+        score += 5;
+    if (typeof checks.complexity === 'number' && checks.complexity < 10)
+        score += 5;
+    const grade = score >= 90 ? 'A' : score >= 80 ? 'B' : score >= 70 ? 'C' : score >= 60 ? 'D' : 'F';
+    return { score, maxScore, grade };
+}
+export default MaintainabilityRules;
+//# sourceMappingURL=ts.rules.js.map

package/dist/packages/domain/src/constitution/observability/index.js

@@ -0,0 +1,43 @@
+/**
+ * Delta Constitution - Observability Rules Index
+ * @description Observability rules for all supported languages
+ * @version 1.0.0
+ */
+// TypeScript / Node.js Rules
+export { default as ts, ObservabilityRules as TSObservabilityRules } from './ts.rules';
+// Language-agnostic exports
+export const ObservabilityAxis = {
+    name: 'Observability',
+    description: 'Health Checks, Logging, Metrics, Error Tracking, Alerting',
+    weight: 5,
+    languages: ['typescript', 'javascript', 'node'],
+    principles: [
+        {
+            id: 'OBS-001',
+            name: 'Health Checks',
+            description: 'Every service exposes /api/health, /api/ready, /api/live',
+        },
+        {
+            id: 'OBS-002',
+            name: 'Structured Logging',
+            description: 'JSON structured logs across all layers',
+        },
+        {
+            id: 'OBS-003',
+            name: 'Error Tracking',
+            description: 'Centralized error tracking with context',
+        },
+        {
+            id: 'OBS-004',
+            name: 'Performance Metrics',
+            description: 'Track latency, throughput, errors, business metrics',
+        },
+        {
+            id: 'OBS-005',
+            name: 'Alerting',
+            description: 'Proactive alerts for critical issues',
+        },
+    ],
+};
+export default ObservabilityAxis;
+//# sourceMappingURL=index.js.map

package/dist/packages/domain/src/constitution/observability/ts.rules.js

@@ -0,0 +1,307 @@
+/**
+ * Delta Constitution - Observability Rules
+ * @description Monitoring, logging, and health check standards
+ * @version 1.0.0
+ * @see docs/architecture/CONSTITUTION.md
+ */
+// =============================================================================
+// OBSERVABILITY RULE DEFINITIONS
+// =============================================================================
+export const ObservabilityRules = {
+    version: '1.0.0',
+    lastUpdated: '2026-02-10',
+    // ============================================================================
+    // 1. HEALTH CHECKS
+    // ============================================================================
+    healthChecks: {
+        enabled: true,
+        required: true,
+        description: 'Health checks for every endpoint and service',
+        endpoints: {
+            main: {
+                path: '/api/health',
+                method: 'GET',
+                checks: ['database', 'cache', 'storage'],
+                response: {
+                    status: 'healthy | degraded | unhealthy',
+                    timestamp: 'ISO 8601',
+                    version: 'app version',
+                    checks: 'Record<string, boolean> - Health check results',
+                },
+            },
+            ready: {
+                path: '/api/ready',
+                method: 'GET',
+                purpose: 'Kubernetes readiness probe',
+                checks: ['dependencies ready'],
+            },
+            live: {
+                path: '/api/live',
+                method: 'GET',
+                purpose: 'Kubernetes liveness probe',
+                checks: ['process running'],
+            },
+        },
+        requirements: {
+            allServices: true,
+            responseTime: '< 500ms',
+            frequency: 'configurable',
+            alerting: true,
+        },
+        rules: [
+            {
+                id: 'OBS-HEALTH-001',
+                name: 'Health Endpoint Required',
+                description: 'Every service must expose /api/health',
+                severity: 'error',
+            },
+            {
+                id: 'OBS-HEALTH-002',
+                name: 'Dependency Checks',
+                description: 'Health check must verify all dependencies',
+                severity: 'error',
+            },
+        ],
+    },
+    // ============================================================================
+    // 2. STRUCTURED LOGGING
+    // ============================================================================
+    structuredLogging: {
+        enabled: true,
+        required: true,
+        description: 'JSON structured logging across all layers',
+        format: {
+            type: 'JSON',
+            required: ['timestamp', 'level', 'message', 'service'],
+            optional: ['traceId', 'userId', 'duration', 'metadata'],
+        },
+        levels: {
+            fatal: { level: 60, use: 'Application crash' },
+            error: { level: 50, use: 'Errors requiring immediate attention' },
+            warn: { level: 40, use: 'Warnings, recoverable issues' },
+            info: { level: 30, use: 'General information' },
+            debug: { level: 20, use: 'Debugging information' },
+            trace: { level: 10, use: 'Detailed tracing' },
+        },
+        layers: {
+            features: { level: 'info', purpose: 'User actions, UI events' },
+            modules: { level: 'info', purpose: 'Business logic operations' },
+            core: { level: 'debug', purpose: 'Domain logic details' },
+            security: { level: 'info', purpose: 'Audit events, violations' },
+            infrastructure: { level: 'warn', purpose: 'External service issues' },
+        },
+        tools: {
+            development: 'pino-pretty',
+            production: 'pino',
+            transport: 'stdout (containerized)',
+        },
+    },
+    // ============================================================================
+    // 3. ERROR TRACKING
+    // ============================================================================
+    errorTracking: {
+        enabled: true,
+        required: true,
+        description: 'Centralized error tracking and alerting',
+        tools: {
+            primary: 'Sentry',
+            fallback: 'Custom error aggregation',
+        },
+        requirements: {
+            capture: ['exceptions', 'unhandled rejections', 'crashes'],
+            context: ['user', 'request', 'tags', 'breadcrumbs'],
+            alerting: {
+                channels: ['email', 'slack', 'pagerduty'],
+                rules: [
+                    { condition: 'error rate > 1%', level: 'warning' },
+                    { condition: 'error rate > 5%', level: 'critical' },
+                    { condition: 'fatal error', level: 'critical' },
+                ],
+            },
+        },
+        rules: [
+            {
+                id: 'OBS-ERR-001',
+                name: 'Error Context',
+                description: 'All errors must include user and request context',
+                severity: 'error',
+            },
+            {
+                id: 'OBS-ERR-002',
+                name: 'Alert Threshold',
+                description: 'Alert when error rate exceeds 1%',
+                severity: 'warning',
+            },
+        ],
+    },
+    // ============================================================================
+    // 4. PERFORMANCE METRICS
+    // ============================================================================
+    performanceMetrics: {
+        enabled: true,
+        required: true,
+        description: 'Performance tracking and dashboards',
+        metrics: {
+            api: {
+                latency: { p50: '100ms', p95: '300ms', p99: '500ms' },
+                throughput: 'requests per second',
+                errors: 'error rate percentage',
+            },
+            frontend: {
+                ttfb: 'Time to first byte',
+                fcp: 'First contentful paint',
+                lcp: 'Largest contentful paint',
+                tti: 'Time to interactive',
+                cls: 'Cumulative layout shift',
+            },
+            business: {
+                activeUsers: 'Concurrent users',
+                featureUsage: 'Feature adoption rates',
+                conversion: 'User conversion rates',
+            },
+        },
+        targets: {
+            lighthouse: {
+                performance: 90,
+                accessibility: 90,
+                'best-practices': 90,
+                seo: 90,
+            },
+            api: {
+                p95: '300ms',
+                p99: '500ms',
+                errorRate: '0.1%',
+            },
+        },
+        dashboards: {
+            grafana: 'Primary dashboard',
+            vercel: 'Built-in analytics',
+            custom: 'Custom business metrics',
+        },
+    },
+    // ============================================================================
+    // 5. DISTRIBUTED TRACING
+    // ============================================================================
+    distributedTracing: {
+        enabled: true,
+        required: false,
+        description: 'Trace requests across services',
+        implementation: {
+            tool: 'OpenTelemetry',
+            propagation: 'W3C Trace Context',
+            sampling: '1% in production, 100% in development',
+        },
+        spans: {
+            required: ['request', 'database', 'cache', 'external-api'],
+            optional: ['render', 'compute', 'validation'],
+        },
+    },
+    // ============================================================================
+    // 6. ALERTING
+    // ============================================================================
+    alerting: {
+        enabled: true,
+        required: true,
+        description: 'Proactive alerting for issues',
+        channels: {
+            slack: { type: 'notification', use: 'team alerts' },
+            email: { type: 'notification', use: 'summary reports' },
+            pagerduty: { type: 'pager', use: 'critical issues' },
+        },
+        rules: [
+            {
+                id: 'OBS-ALERT-001',
+                condition: 'Health check fails',
+                severity: 'critical',
+                channel: 'pagerduty',
+                response: 'immediate',
+            },
+            {
+                id: 'OBS-ALERT-002',
+                condition: 'Error rate > 1%',
+                severity: 'warning',
+                channel: 'slack',
+                response: 'within 15 min',
+            },
+            {
+                id: 'OBS-ALERT-003',
+                condition: 'API latency p95 > 500ms',
+                severity: 'warning',
+                channel: 'slack',
+                response: 'within 30 min',
+            },
+            {
+                id: 'OBS-ALERT-004',
+                condition: 'Security policy violation',
+                severity: 'critical',
+                channel: 'pagerduty + slack',
+                response: 'immediate',
+            },
+        ],
+    },
+};
+// =============================================================================
+// VALIDATION HELPERS
+// =============================================================================
+export function validateObservabilityCompliance(checks) {
+    const violations = [];
+    let score = 100;
+    if (!checks.hasHealthEndpoint) {
+        violations.push('OBS-HEALTH-001: Missing health endpoint');
+        score -= 20;
+    }
+    if (!checks.hasStructuredLogging) {
+        violations.push('OBS-LOG-001: Missing structured logging');
+        score -= 20;
+    }
+    if (!checks.hasErrorTracking) {
+        violations.push('OBS-ERR-001: Missing error tracking');
+        score -= 20;
+    }
+    if (!checks.hasMetrics) {
+        violations.push('OBS-MET-001: Missing performance metrics');
+        score -= 15;
+    }
+    if (!checks.hasAlerting) {
+        violations.push('OBS-ALERT-001: Missing alerting configuration');
+        score -= 15;
+    }
+    return {
+        compliant: violations.length === 0,
+        violations,
+        score: Math.max(0, score),
+    };
+}
+export function calculateObservabilityScore(checks) {
+    const maxScore = 100;
+    let score = 0;
+    // Health checks (25 points)
+    if (checks.hasHealthEndpoint)
+        score += 15;
+    if (checks.hasReadinessProbe)
+        score += 5;
+    if (checks.hasLivenessProbe)
+        score += 5;
+    // Logging (25 points)
+    if (checks.hasStructuredLogging)
+        score += 15;
+    if (checks.hasLogAggregation)
+        score += 10;
+    // Error tracking (20 points)
+    if (checks.hasErrorTracking)
+        score += 15;
+    if (checks.hasErrorAlerting)
+        score += 5;
+    // Metrics (20 points)
+    if (checks.hasMetrics)
+        score += 15;
+    if (checks.hasDashboards)
+        score += 5;
+    // Alerting (10 points)
+    if (checks.hasAlerting)
+        score += 10;
+    const grade = score >= 90 ? 'A' : score >= 80 ? 'B' : score >= 70 ? 'C' : score >= 60 ? 'D' : 'F';
+    return { score, maxScore, grade };
+}
+export default ObservabilityRules;
+//# sourceMappingURL=ts.rules.js.map