timonel 3.0.0 → 3.1.0

package/dist/lib/policy/resultAggregator.js

@@ -0,0 +1,138 @@
+export function aggregateResults(results) {
+    if (results.length === 0) {
+        return createEmptyResult();
+    }
+    if (results.length === 1) {
+        const result = results[0];
+        return result || createEmptyResult();
+    }
+    const violations = [];
+    const warnings = [];
+    let totalExecutionTime = 0;
+    let totalPluginCount = 0;
+    let totalManifestCount = 0;
+    let earliestStartTime;
+    for (const result of results) {
+        violations.push(...result.violations);
+        warnings.push(...result.warnings);
+        totalExecutionTime += result.metadata.executionTime;
+        totalPluginCount += result.metadata.pluginCount;
+        totalManifestCount = Math.max(totalManifestCount, result.metadata.manifestCount);
+        if (result.metadata.startTime &&
+            (!earliestStartTime || result.metadata.startTime < earliestStartTime)) {
+            earliestStartTime = result.metadata.startTime;
+        }
+    }
+    const metadata = {
+        executionTime: totalExecutionTime,
+        pluginCount: totalPluginCount,
+        manifestCount: totalManifestCount,
+        ...(earliestStartTime && { startTime: earliestStartTime }),
+        aggregatedResults: results.length,
+    };
+    const aggregatedResult = {
+        valid: violations.length === 0,
+        violations,
+        warnings,
+        metadata,
+        summary: generateResultSummary(violations, warnings),
+    };
+    return aggregatedResult;
+}
+export function generateResultSummary(violations, warnings, allPlugins) {
+    const allViolations = [...violations, ...warnings];
+    const violationsBySeverity = {
+        error: violations.filter((v) => v.severity === 'error').length,
+        warning: allViolations.filter((v) => v.severity === 'warning').length,
+        info: allViolations.filter((v) => v.severity === 'info').length,
+    };
+    const violationsByPlugin = Object.create(null);
+    if (allPlugins) {
+        for (const pluginName of allPlugins) {
+            violationsByPlugin[pluginName] = 0;
+        }
+    }
+    for (const violation of allViolations) {
+        const pluginName = violation.plugin;
+        violationsByPlugin[pluginName] = (violationsByPlugin[pluginName] || 0) + 1;
+    }
+    const violationTypeCount = Object.create(null);
+    for (const violation of allViolations) {
+        const type = extractViolationType(violation.message);
+        violationTypeCount[type] = (violationTypeCount[type] || 0) + 1;
+    }
+    const topViolationTypes = Object.entries(violationTypeCount)
+        .map(([type, count]) => ({ type, count }))
+        .sort((a, b) => b.count - a.count)
+        .slice(0, 5);
+    return {
+        violationsBySeverity,
+        violationsByPlugin,
+        topViolationTypes,
+    };
+}
+export function filterViolationsBySeverity(violations, severity) {
+    return violations.filter((v) => v.severity === severity);
+}
+export function groupViolationsByPlugin(violations) {
+    const grouped = Object.create(null);
+    for (const violation of violations) {
+        const pluginName = violation.plugin;
+        if (!grouped[pluginName]) {
+            grouped[pluginName] = [];
+        }
+        grouped[pluginName].push(violation);
+    }
+    return grouped;
+}
+export function sortViolationsBySeverity(violations) {
+    const severityOrder = { error: 0, warning: 1, info: 2 };
+    return [...violations].sort((a, b) => {
+        const orderA = severityOrder[a.severity];
+        const orderB = severityOrder[b.severity];
+        if (orderA !== orderB) {
+            return orderA - orderB;
+        }
+        if (a.plugin !== b.plugin) {
+            return a.plugin.localeCompare(b.plugin);
+        }
+        return a.message.localeCompare(b.message);
+    });
+}
+export function createEmptyResult() {
+    const metadata = {
+        executionTime: 0,
+        pluginCount: 0,
+        manifestCount: 0,
+    };
+    return {
+        valid: true,
+        violations: [],
+        warnings: [],
+        metadata,
+        summary: {
+            violationsBySeverity: { error: 0, warning: 0, info: 0 },
+            violationsByPlugin: {},
+            topViolationTypes: [],
+        },
+    };
+}
+function extractViolationType(message) {
+    const sentences = message.split('.');
+    const firstSentence = sentences.length > 0 ? sentences[0] : message;
+    if (firstSentence && firstSentence.length <= 50) {
+        return firstSentence.trim();
+    }
+    return message.substring(0, 50).trim() + '...';
+}
+export function mergeViolationContexts(contexts) {
+    const merged = Object.create(null);
+    for (const context of contexts) {
+        if (context && typeof context === 'object') {
+            for (const [key, value] of Object.entries(context)) {
+                merged[key] = value;
+            }
+        }
+    }
+    return merged;
+}

package/dist/lib/policy/resultFormatter.d.ts

@@ -0,0 +1,25 @@
+import type { PolicyResult, ResultFormatter } from './types.js';
+export declare class DefaultResultFormatter implements ResultFormatter {
+    format(result: PolicyResult): string;
+    private formatViolation;
+    private getSeverityIcon;
+}
+export declare class JsonResultFormatter implements ResultFormatter {
+    private indent;
+    constructor(indent?: number);
+    format(result: PolicyResult): string;
+}
+export declare class CompactResultFormatter implements ResultFormatter {
+    format(result: PolicyResult): string;
+}
+export declare class GitHubActionsResultFormatter implements ResultFormatter {
+    format(result: PolicyResult): string;
+}
+export declare class SarifResultFormatter implements ResultFormatter {
+    format(result: PolicyResult): string;
+    private convertViolationsToSarifResults;
+    private generateRuleId;
+    private mapSeverityToSarifLevel;
+}
+export declare function createFormatter(name: string, options?: Record<string, unknown>): ResultFormatter;
+export declare function getAvailableFormatters(): string[];

package/dist/lib/policy/resultFormatter.js

@@ -0,0 +1,217 @@
+import { sortViolationsBySeverity } from './resultAggregator.js';
+export class DefaultResultFormatter {
+    format(result) {
+        const lines = [];
+        lines.push('='.repeat(60));
+        lines.push('Policy Validation Results');
+        lines.push('='.repeat(60));
+        const status = result.valid ? '✅ PASSED' : '❌ FAILED';
+        lines.push(`Status: ${status}`);
+        lines.push('');
+        if (result.summary) {
+            lines.push('Summary:');
+            lines.push(`  Errors:   ${result.summary.violationsBySeverity.error}`);
+            lines.push(`  Warnings: ${result.summary.violationsBySeverity.warning}`);
+            lines.push(`  Info:     ${result.summary.violationsBySeverity.info}`);
+            lines.push('');
+        }
+        lines.push('Execution Details:');
+        lines.push(`  Plugins:   ${result.metadata.pluginCount}`);
+        lines.push(`  Manifests: ${result.metadata.manifestCount}`);
+        lines.push(`  Duration:  ${result.metadata.executionTime}ms`);
+        lines.push('');
+        if (result.violations.length > 0) {
+            lines.push('Violations:');
+            lines.push('-'.repeat(40));
+            const sortedViolations = sortViolationsBySeverity(result.violations);
+            for (const violation of sortedViolations) {
+                lines.push(this.formatViolation(violation));
+                lines.push('');
+            }
+        }
+        if (result.warnings.length > 0) {
+            lines.push('Warnings:');
+            lines.push('-'.repeat(40));
+            const sortedWarnings = sortViolationsBySeverity(result.warnings);
+            for (const warning of sortedWarnings) {
+                lines.push(this.formatViolation(warning));
+                lines.push('');
+            }
+        }
+        if (result.violations.length === 0 && result.warnings.length === 0) {
+            lines.push('✨ No policy violations found!');
+            lines.push('');
+        }
+        return lines.join('\n');
+    }
+    formatViolation(violation) {
+        const lines = [];
+        const severityIcon = this.getSeverityIcon(violation.severity);
+        lines.push(`${severityIcon} [${violation.plugin}] ${violation.message}`);
+        if (violation.resourcePath) {
+            lines.push(`   Resource: ${violation.resourcePath}`);
+        }
+        if (violation.field) {
+            lines.push(`   Field: ${violation.field}`);
+        }
+        if (violation.suggestion) {
+            lines.push(`   💡 Suggestion: ${violation.suggestion}`);
+        }
+        return lines.join('\n');
+    }
+    getSeverityIcon(severity) {
+        switch (severity) {
+            case 'error':
+                return '🚨';
+            case 'warning':
+                return '⚠️';
+            case 'info':
+                return 'ℹ️';
+            default:
+                return '•';
+        }
+    }
+}
+export class JsonResultFormatter {
+    constructor(indent = 2) {
+        this.indent = indent;
+    }
+    format(result) {
+        return JSON.stringify(result, null, this.indent);
+    }
+}
+export class CompactResultFormatter {
+    format(result) {
+        const status = result.valid ? 'PASS' : 'FAIL';
+        const errorCount = result.violations.filter((v) => v.severity === 'error').length;
+        const warningCount = [...result.violations, ...result.warnings].filter((v) => v.severity === 'warning' || v.severity === 'info').length;
+        let output = `Policy validation: ${status}`;
+        if (errorCount > 0 || warningCount > 0) {
+            output += ` (${errorCount} errors, ${warningCount} warnings)`;
+        }
+        output += ` - ${result.metadata.executionTime}ms`;
+        if (!result.valid && result.violations.length > 0) {
+            output += '\n';
+            const firstViolations = result.violations.slice(0, 3);
+            for (const violation of firstViolations) {
+                output += `\n  • [${violation.plugin}] ${violation.message}`;
+            }
+            if (result.violations.length > 3) {
+                output += `\n  ... and ${result.violations.length - 3} more`;
+            }
+        }
+        return output;
+    }
+}
+export class GitHubActionsResultFormatter {
+    format(result) {
+        const lines = [];
+        const status = result.valid ? 'success' : 'failure';
+        lines.push(`::notice title=Policy Validation::Status: ${status}`);
+        for (const violation of result.violations) {
+            const level = violation.severity === 'error' ? 'error' : 'warning';
+            const file = violation.resourcePath || 'unknown';
+            const message = `[${violation.plugin}] ${violation.message}`;
+            lines.push(`::${level} file=${file}::${message}`);
+        }
+        for (const warning of result.warnings) {
+            const level = warning.severity === 'info' ? 'notice' : 'warning';
+            const file = warning.resourcePath || 'unknown';
+            const message = `[${warning.plugin}] ${warning.message}`;
+            lines.push(`::${level} file=${file}::${message}`);
+        }
+        return lines.join('\n');
+    }
+}
+export class SarifResultFormatter {
+    format(result) {
+        const runs = [
+            {
+                tool: {
+                    driver: {
+                        name: 'Timonel Policy Engine',
+                        version: '3.0.0',
+                        informationUri: 'https://github.com/your-org/timonel',
+                    },
+                },
+                results: this.convertViolationsToSarifResults([...result.violations, ...result.warnings]),
+            },
+        ];
+        const sarif = {
+            version: '2.1.0',
+            $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+            runs,
+        };
+        return JSON.stringify(sarif, null, 2);
+    }
+    convertViolationsToSarifResults(violations) {
+        return violations.map((violation) => ({
+            ruleId: `${violation.plugin}/${this.generateRuleId(violation.message)}`,
+            level: this.mapSeverityToSarifLevel(violation.severity),
+            message: {
+                text: violation.message,
+            },
+            locations: violation.resourcePath
+                ? [
+                    {
+                        physicalLocation: {
+                            artifactLocation: {
+                                uri: violation.resourcePath,
+                            },
+                            region: violation.field
+                                ? {
+                                    startLine: 1,
+                                    startColumn: 1,
+                                }
+                                : undefined,
+                        },
+                    },
+                ]
+                : [],
+            properties: {
+                plugin: violation.plugin,
+                suggestion: violation.suggestion,
+                context: violation.context,
+            },
+        }));
+    }
+    generateRuleId(message) {
+        return message
+            .toLowerCase()
+            .replace(/[^a-z0-9\s]/g, '')
+            .replace(/\s+/g, '-')
+            .substring(0, 50);
+    }
+    mapSeverityToSarifLevel(severity) {
+        switch (severity) {
+            case 'error':
+                return 'error';
+            case 'warning':
+                return 'warning';
+            case 'info':
+                return 'note';
+            default:
+                return 'note';
+        }
+    }
+}
+export function createFormatter(name, options) {
+    switch (name.toLowerCase()) {
+        case 'default':
+            return new DefaultResultFormatter();
+        case 'json':
+            return new JsonResultFormatter(options?.indent);
+        case 'compact':
+            return new CompactResultFormatter();
+        case 'github':
+        case 'github-actions':
+            return new GitHubActionsResultFormatter();
+        case 'sarif':
+            return new SarifResultFormatter();
+        default:
+            throw new Error(`Unknown formatter: ${name}`);
+    }
+}
+export function getAvailableFormatters() {
+    return ['default', 'json', 'compact', 'github-actions', 'sarif'];
+}

package/dist/lib/policy/types.d.ts

@@ -0,0 +1,111 @@
+import type { TimonelLogger } from '../utils/logger.js';
+import type { ChartMetadata } from '../rutter.js';
+import type { ValidationOptions } from '../validation/inputValidator.js';
+import type { CacheOptions } from './validationCache.js';
+import type { ParallelExecutionOptions } from './parallelExecutor.js';
+export interface JSONSchema {
+    type?: string;
+    properties?: Record<string, JSONSchema>;
+    required?: string[];
+    additionalProperties?: boolean | JSONSchema;
+    [key: string]: unknown;
+}
+export interface PluginMetadata {
+    author?: string;
+    license?: string;
+    homepage?: string;
+    repository?: string;
+    kubernetesVersions?: string[];
+    tags?: string[];
+    defaultConfig?: Record<string, unknown>;
+}
+export interface ValidationContext {
+    readonly chart: ChartMetadata;
+    readonly kubernetesVersion?: string;
+    readonly environment?: string;
+    readonly config?: Record<string, unknown>;
+    readonly logger: TimonelLogger;
+}
+export interface PolicyViolation {
+    readonly plugin: string;
+    readonly severity: 'error' | 'warning' | 'info';
+    readonly message: string;
+    readonly resourcePath?: string;
+    readonly field?: string;
+    readonly suggestion?: string;
+    readonly context?: Record<string, unknown>;
+}
+export interface PolicyWarning extends Omit<PolicyViolation, 'severity'> {
+    readonly severity: 'warning' | 'info';
+}
+export interface ValidationMetadata {
+    readonly executionTime: number;
+    readonly pluginCount: number;
+    readonly manifestCount: number;
+    readonly startTime?: number;
+    readonly [key: string]: unknown;
+}
+export interface PolicyResult {
+    readonly valid: boolean;
+    readonly violations: PolicyViolation[];
+    readonly warnings: PolicyWarning[];
+    readonly metadata: ValidationMetadata;
+    readonly summary?: ResultSummary;
+}
+export interface ResultSummary {
+    readonly violationsBySeverity: {
+        readonly error: number;
+        readonly warning: number;
+        readonly info: number;
+    };
+    readonly violationsByPlugin: Record<string, number>;
+    readonly topViolationTypes: Array<{
+        readonly type: string;
+        readonly count: number;
+    }>;
+}
+export interface PolicyPlugin {
+    readonly name: string;
+    readonly version: string;
+    readonly description?: string;
+    validate(manifests: unknown[], context: ValidationContext): Promise<PolicyViolation[]>;
+    readonly configSchema?: JSONSchema;
+    readonly metadata?: PluginMetadata;
+}
+export interface ResultFormatter {
+    format(result: PolicyResult): string;
+}
+export interface RetryConfig {
+    maxAttempts: number;
+    baseDelay: number;
+    backoffMultiplier: number;
+    maxDelay: number;
+    retryOnTimeout: boolean;
+    retryOnPluginError: boolean;
+}
+export interface ConfigurationLoaderOptions {
+    defaultEnvironment?: string;
+    validateSchemas?: boolean;
+    allowUnknownProperties?: boolean;
+    configurationFiles?: string[];
+    environmentPrefix?: string;
+}
+export interface PolicyEngineOptions {
+    timeout?: number;
+    parallel?: boolean;
+    failFast?: boolean;
+    formatter?: ResultFormatter;
+    pluginConfig?: Record<string, unknown>;
+    retryConfig?: RetryConfig;
+    gracefulDegradation?: boolean;
+    configurationLoader?: ConfigurationLoaderOptions;
+    environment?: string;
+    cacheOptions?: CacheOptions;
+    parallelOptions?: ParallelExecutionOptions;
+    validationOptions?: ValidationOptions;
+}
+export interface PolicyEngine {
+    use(plugin: PolicyPlugin): Promise<PolicyEngine>;
+    validate(manifests: unknown[], chartMetadata: ChartMetadata): Promise<PolicyResult>;
+    configure(options: PolicyEngineOptions): PolicyEngine;
+}

package/dist/lib/policy/types.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/policy/validationCache.d.ts

@@ -0,0 +1,58 @@
+import type { PolicyResult } from './types.js';
+export interface CacheEntry {
+    readonly result: PolicyResult;
+    readonly timestamp: number;
+    readonly manifestHash: string;
+    readonly pluginHash: string;
+    accessCount: number;
+    lastAccessed: number;
+}
+export interface CacheOptions {
+    maxEntries?: number;
+    maxAge?: number;
+    enableCompression?: boolean;
+    evictionStrategy?: 'lru' | 'lfu' | 'ttl';
+    cacheFailures?: boolean;
+    minExecutionTimeToCache?: number;
+}
+export interface CacheStats {
+    hits: number;
+    misses: number;
+    entries: number;
+    memoryUsage: number;
+    hitRatio: number;
+    averageAccessCount: number;
+}
+export declare class ValidationCache {
+    private readonly cache;
+    private readonly options;
+    private readonly logger;
+    private stats;
+    constructor(options?: CacheOptions);
+    get(manifestHash: string, pluginHash: string): PolicyResult | undefined;
+    set(manifestHash: string, pluginHash: string, result: PolicyResult): void;
+    invalidate(criteria: {
+        manifestHash?: string;
+        pluginHash?: string;
+        olderThan?: number;
+        all?: boolean;
+    }): number;
+    private invalidateAll;
+    private invalidateSelective;
+    private shouldInvalidateEntry;
+    getStats(): CacheStats;
+    clearStats(): void;
+    private generateCacheKey;
+    private isExpired;
+    private shouldCache;
+    private evictEntries;
+    private evictLRU;
+    private evictLFU;
+    private evictTTL;
+    private updateStats;
+    private estimateMemoryUsage;
+    private startPeriodicCleanup;
+    private cleanupExpiredEntries;
+}
+export declare function generateManifestHash(manifests: unknown[]): string;
+export declare function generatePluginHash(plugins: string[], pluginConfigs: Record<string, unknown>): string;