timonel 3.1.1 → 3.1.2

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

@@ -1,8 +1,54 @@
+/**
+ * Result Aggregation Utilities
+ *
+ * This module provides utilities for aggregating and processing policy validation results.
+ * It includes functions for combining results from multiple plugins, generating summaries,
+ * and formatting output.
+ *
+ * @since 3.0.0
+ */
 import type { PolicyResult, PolicyViolation, PolicyWarning, ResultSummary } from './types.js';
+/**
+ * Aggregates multiple policy results into a single result
+ * @param results - Array of policy results to aggregate
+ * @returns Aggregated policy result
+ */
 export declare function aggregateResults(results: PolicyResult[]): PolicyResult;
+/**
+ * Generates a summary of validation results
+ * @param violations - Array of policy violations
+ * @param warnings - Array of policy warnings
+ * @param allPlugins - Array of all plugins that were executed (optional)
+ * @returns Result summary with statistics
+ */
 export declare function generateResultSummary(violations: PolicyViolation[], warnings: PolicyWarning[], allPlugins?: string[]): ResultSummary;
+/**
+ * Filters violations by severity level
+ * @param violations - Array of violations to filter
+ * @param severity - Severity level to filter by
+ * @returns Filtered violations
+ */
 export declare function filterViolationsBySeverity(violations: PolicyViolation[], severity: 'error' | 'warning' | 'info'): PolicyViolation[];
+/**
+ * Groups violations by plugin name
+ * @param violations - Array of violations to group
+ * @returns Violations grouped by plugin name
+ */
 export declare function groupViolationsByPlugin(violations: PolicyViolation[]): Record<string, PolicyViolation[]>;
+/**
+ * Sorts violations by severity (error > warning > info)
+ * @param violations - Array of violations to sort
+ * @returns Sorted violations
+ */
 export declare function sortViolationsBySeverity(violations: PolicyViolation[]): PolicyViolation[];
+/**
+ * Creates an empty policy result for cases with no violations
+ * @returns Empty policy result
+ */
 export declare function createEmptyResult(): PolicyResult;
+/**
+ * Merges violation context objects safely
+ * @param contexts - Array of context objects to merge
+ * @returns Merged context object
+ */
 export declare function mergeViolationContexts(contexts: Array<Record<string, unknown> | undefined>): Record<string, unknown>;

package/dist/lib/policy/resultAggregator.js

@@ -1,3 +1,17 @@
+/**
+ * Result Aggregation Utilities
+ *
+ * This module provides utilities for aggregating and processing policy validation results.
+ * It includes functions for combining results from multiple plugins, generating summaries,
+ * and formatting output.
+ *
+ * @since 3.0.0
+ */
+/**
+ * Aggregates multiple policy results into a single result
+ * @param results - Array of policy results to aggregate
+ * @returns Aggregated policy result
+ */
 export function aggregateResults(results) {
     if (results.length === 0) {
         return createEmptyResult();
@@ -39,52 +53,87 @@ export function aggregateResults(results) {
     };
     return aggregatedResult;
 }
+/**
+ * Generates a summary of validation results
+ * @param violations - Array of policy violations
+ * @param warnings - Array of policy warnings
+ * @param allPlugins - Array of all plugins that were executed (optional)
+ * @returns Result summary with statistics
+ */
 export function generateResultSummary(violations, warnings, allPlugins) {
     const allViolations = [...violations, ...warnings];
+    // Count violations by severity
     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,
     };
+    // Count violations by plugin
     const violationsByPlugin = Object.create(null);
+    // Initialize all plugins with 0 violations if provided
     if (allPlugins) {
         for (const pluginName of allPlugins) {
+            // eslint-disable-next-line security/detect-object-injection
             violationsByPlugin[pluginName] = 0;
         }
     }
+    // Count actual violations
     for (const violation of allViolations) {
         const pluginName = violation.plugin;
+        // eslint-disable-next-line security/detect-object-injection
         violationsByPlugin[pluginName] = (violationsByPlugin[pluginName] || 0) + 1;
     }
+    // Find top violation types (based on message patterns)
     const violationTypeCount = Object.create(null);
     for (const violation of allViolations) {
+        // Extract violation type from message (first sentence or first 50 chars)
         const type = extractViolationType(violation.message);
+        // eslint-disable-next-line security/detect-object-injection
         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);
+        .slice(0, 5); // Top 5 violation types
     return {
         violationsBySeverity,
         violationsByPlugin,
         topViolationTypes,
     };
 }
+/**
+ * Filters violations by severity level
+ * @param violations - Array of violations to filter
+ * @param severity - Severity level to filter by
+ * @returns Filtered violations
+ */
 export function filterViolationsBySeverity(violations, severity) {
     return violations.filter((v) => v.severity === severity);
 }
+/**
+ * Groups violations by plugin name
+ * @param violations - Array of violations to group
+ * @returns Violations grouped by plugin name
+ */
 export function groupViolationsByPlugin(violations) {
     const grouped = Object.create(null);
     for (const violation of violations) {
         const pluginName = violation.plugin;
+        // eslint-disable-next-line security/detect-object-injection
         if (!grouped[pluginName]) {
+            // eslint-disable-next-line security/detect-object-injection
             grouped[pluginName] = [];
         }
+        // eslint-disable-next-line security/detect-object-injection
         grouped[pluginName].push(violation);
     }
     return grouped;
 }
+/**
+ * Sorts violations by severity (error > warning > info)
+ * @param violations - Array of violations to sort
+ * @returns Sorted violations
+ */
 export function sortViolationsBySeverity(violations) {
     const severityOrder = { error: 0, warning: 1, info: 2 };
     return [...violations].sort((a, b) => {
@@ -93,12 +142,17 @@ export function sortViolationsBySeverity(violations) {
         if (orderA !== orderB) {
             return orderA - orderB;
         }
+        // If same severity, sort by plugin name, then by message
         if (a.plugin !== b.plugin) {
             return a.plugin.localeCompare(b.plugin);
         }
         return a.message.localeCompare(b.message);
     });
 }
+/**
+ * Creates an empty policy result for cases with no violations
+ * @returns Empty policy result
+ */
 export function createEmptyResult() {
     const metadata = {
         executionTime: 0,
@@ -117,19 +171,33 @@ export function createEmptyResult() {
         },
     };
 }
+/**
+ * Extracts a violation type identifier from a violation message
+ * @param message - Violation message
+ * @returns Violation type string
+ * @private
+ */
 function extractViolationType(message) {
+    // Try to extract the first sentence
     const sentences = message.split('.');
     const firstSentence = sentences.length > 0 ? sentences[0] : message;
     if (firstSentence && firstSentence.length <= 50) {
         return firstSentence.trim();
     }
+    // If first sentence is too long, take first 50 characters
     return message.substring(0, 50).trim() + '...';
 }
+/**
+ * Merges violation context objects safely
+ * @param contexts - Array of context objects to merge
+ * @returns Merged context object
+ */
 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)) {
+                // eslint-disable-next-line security/detect-object-injection
                 merged[key] = value;
             }
         }

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

@@ -1,25 +1,113 @@
+/**
+ * Result Formatters
+ *
+ * This module provides formatters for policy validation results, including
+ * default formatters and support for custom formatting.
+ *
+ * @since 3.0.0
+ */
 import type { PolicyResult, ResultFormatter } from './types.js';
+/**
+ * Default result formatter that provides human-readable output
+ */
 export declare class DefaultResultFormatter implements ResultFormatter {
+    /**
+     * Formats validation results for output
+     * @param result - Validation result to format
+     * @returns Formatted string representation
+     */
     format(result: PolicyResult): string;
+    /**
+     * Formats a single violation for display
+     * @param violation - Violation to format
+     * @returns Formatted violation string
+     * @private
+     */
     private formatViolation;
+    /**
+     * Gets the appropriate icon for a severity level
+     * @param severity - Severity level
+     * @returns Icon string
+     * @private
+     */
     private getSeverityIcon;
 }
+/**
+ * JSON result formatter that outputs structured JSON
+ */
 export declare class JsonResultFormatter implements ResultFormatter {
     private indent;
     constructor(indent?: number);
+    /**
+     * Formats validation results as JSON
+     * @param result - Validation result to format
+     * @returns JSON string representation
+     */
     format(result: PolicyResult): string;
 }
+/**
+ * Compact result formatter for CI/CD environments
+ */
 export declare class CompactResultFormatter implements ResultFormatter {
+    /**
+     * Formats validation results in a compact format
+     * @param result - Validation result to format
+     * @returns Compact string representation
+     */
     format(result: PolicyResult): string;
 }
+/**
+ * GitHub Actions result formatter that outputs in GitHub Actions format
+ */
 export declare class GitHubActionsResultFormatter implements ResultFormatter {
+    /**
+     * Formats validation results for GitHub Actions
+     * @param result - Validation result to format
+     * @returns GitHub Actions formatted string
+     */
     format(result: PolicyResult): string;
 }
+/**
+ * SARIF (Static Analysis Results Interchange Format) result formatter
+ */
 export declare class SarifResultFormatter implements ResultFormatter {
+    /**
+     * Formats validation results as SARIF JSON
+     * @param result - Validation result to format
+     * @returns SARIF JSON string
+     */
     format(result: PolicyResult): string;
+    /**
+     * Converts violations to SARIF results format
+     * @param violations - Violations to convert
+     * @returns SARIF results array
+     * @private
+     */
     private convertViolationsToSarifResults;
+    /**
+     * Generates a rule ID from a violation message
+     * @param message - Violation message
+     * @returns Rule ID string
+     * @private
+     */
     private generateRuleId;
+    /**
+     * Maps violation severity to SARIF level
+     * @param severity - Violation severity
+     * @returns SARIF level string
+     * @private
+     */
     private mapSeverityToSarifLevel;
 }
+/**
+ * Factory function to create formatters by name
+ * @param name - Formatter name
+ * @param options - Formatter options
+ * @returns Result formatter instance
+ */
 export declare function createFormatter(name: string, options?: Record<string, unknown>): ResultFormatter;
+/**
+ * Gets a list of available formatter names
+ * @returns Array of formatter names
+ */
 export declare function getAvailableFormatters(): string[];

package/dist/lib/policy/resultFormatter.js

@@ -1,13 +1,32 @@
+/**
+ * Result Formatters
+ *
+ * This module provides formatters for policy validation results, including
+ * default formatters and support for custom formatting.
+ *
+ * @since 3.0.0
+ */
 import { sortViolationsBySeverity } from './resultAggregator.js';
+/**
+ * Default result formatter that provides human-readable output
+ */
 export class DefaultResultFormatter {
+    /**
+     * Formats validation results for output
+     * @param result - Validation result to format
+     * @returns Formatted string representation
+     */
     format(result) {
         const lines = [];
+        // Header
         lines.push('='.repeat(60));
         lines.push('Policy Validation Results');
         lines.push('='.repeat(60));
+        // Overall status
         const status = result.valid ? '✅ PASSED' : '❌ FAILED';
         lines.push(`Status: ${status}`);
         lines.push('');
+        // Summary statistics
         if (result.summary) {
             lines.push('Summary:');
             lines.push(`  Errors:   ${result.summary.violationsBySeverity.error}`);
@@ -15,11 +34,13 @@ export class DefaultResultFormatter {
             lines.push(`  Info:     ${result.summary.violationsBySeverity.info}`);
             lines.push('');
         }
+        // Execution metadata
         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('');
+        // Violations
         if (result.violations.length > 0) {
             lines.push('Violations:');
             lines.push('-'.repeat(40));
@@ -29,6 +50,7 @@ export class DefaultResultFormatter {
                 lines.push('');
             }
         }
+        // Warnings
         if (result.warnings.length > 0) {
             lines.push('Warnings:');
             lines.push('-'.repeat(40));
@@ -38,27 +60,43 @@ export class DefaultResultFormatter {
                 lines.push('');
             }
         }
+        // No issues message
         if (result.violations.length === 0 && result.warnings.length === 0) {
             lines.push('✨ No policy violations found!');
             lines.push('');
         }
         return lines.join('\n');
     }
+    /**
+     * Formats a single violation for display
+     * @param violation - Violation to format
+     * @returns Formatted violation string
+     * @private
+     */
     formatViolation(violation) {
         const lines = [];
+        // Severity icon and plugin
         const severityIcon = this.getSeverityIcon(violation.severity);
         lines.push(`${severityIcon} [${violation.plugin}] ${violation.message}`);
+        // Resource path and field
         if (violation.resourcePath) {
             lines.push(`   Resource: ${violation.resourcePath}`);
         }
         if (violation.field) {
             lines.push(`   Field: ${violation.field}`);
         }
+        // Suggestion
         if (violation.suggestion) {
             lines.push(`   💡 Suggestion: ${violation.suggestion}`);
         }
         return lines.join('\n');
     }
+    /**
+     * Gets the appropriate icon for a severity level
+     * @param severity - Severity level
+     * @returns Icon string
+     * @private
+     */
     getSeverityIcon(severity) {
         switch (severity) {
             case 'error':
@@ -72,15 +110,31 @@ export class DefaultResultFormatter {
         }
     }
 }
+/**
+ * JSON result formatter that outputs structured JSON
+ */
 export class JsonResultFormatter {
     constructor(indent = 2) {
         this.indent = indent;
     }
+    /**
+     * Formats validation results as JSON
+     * @param result - Validation result to format
+     * @returns JSON string representation
+     */
     format(result) {
         return JSON.stringify(result, null, this.indent);
     }
 }
+/**
+ * Compact result formatter for CI/CD environments
+ */
 export class CompactResultFormatter {
+    /**
+     * Formats validation results in a compact format
+     * @param result - Validation result to format
+     * @returns Compact string representation
+     */
     format(result) {
         const status = result.valid ? 'PASS' : 'FAIL';
         const errorCount = result.violations.filter((v) => v.severity === 'error').length;
@@ -90,6 +144,7 @@ export class CompactResultFormatter {
             output += ` (${errorCount} errors, ${warningCount} warnings)`;
         }
         output += ` - ${result.metadata.executionTime}ms`;
+        // Add first few violations for context
         if (!result.valid && result.violations.length > 0) {
             output += '\n';
             const firstViolations = result.violations.slice(0, 3);
@@ -103,11 +158,21 @@ export class CompactResultFormatter {
         return output;
     }
 }
+/**
+ * GitHub Actions result formatter that outputs in GitHub Actions format
+ */
 export class GitHubActionsResultFormatter {
+    /**
+     * Formats validation results for GitHub Actions
+     * @param result - Validation result to format
+     * @returns GitHub Actions formatted string
+     */
     format(result) {
         const lines = [];
+        // Output summary
         const status = result.valid ? 'success' : 'failure';
         lines.push(`::notice title=Policy Validation::Status: ${status}`);
+        // Output violations as errors/warnings
         for (const violation of result.violations) {
             const level = violation.severity === 'error' ? 'error' : 'warning';
             const file = violation.resourcePath || 'unknown';
@@ -123,7 +188,15 @@ export class GitHubActionsResultFormatter {
         return lines.join('\n');
     }
 }
+/**
+ * SARIF (Static Analysis Results Interchange Format) result formatter
+ */
 export class SarifResultFormatter {
+    /**
+     * Formats validation results as SARIF JSON
+     * @param result - Validation result to format
+     * @returns SARIF JSON string
+     */
     format(result) {
         const runs = [
             {
@@ -144,6 +217,12 @@ export class SarifResultFormatter {
         };
         return JSON.stringify(sarif, null, 2);
     }
+    /**
+     * Converts violations to SARIF results format
+     * @param violations - Violations to convert
+     * @returns SARIF results array
+     * @private
+     */
     convertViolationsToSarifResults(violations) {
         return violations.map((violation) => ({
             ruleId: `${violation.plugin}/${this.generateRuleId(violation.message)}`,
@@ -175,6 +254,12 @@ export class SarifResultFormatter {
             },
         }));
     }
+    /**
+     * Generates a rule ID from a violation message
+     * @param message - Violation message
+     * @returns Rule ID string
+     * @private
+     */
     generateRuleId(message) {
         return message
             .toLowerCase()
@@ -182,6 +267,12 @@ export class SarifResultFormatter {
             .replace(/\s+/g, '-')
             .substring(0, 50);
     }
+    /**
+     * Maps violation severity to SARIF level
+     * @param severity - Violation severity
+     * @returns SARIF level string
+     * @private
+     */
     mapSeverityToSarifLevel(severity) {
         switch (severity) {
             case 'error':
@@ -195,6 +286,12 @@ export class SarifResultFormatter {
         }
     }
 }
+/**
+ * Factory function to create formatters by name
+ * @param name - Formatter name
+ * @param options - Formatter options
+ * @returns Result formatter instance
+ */
 export function createFormatter(name, options) {
     switch (name.toLowerCase()) {
         case 'default':
@@ -212,6 +309,10 @@ export function createFormatter(name, options) {
             throw new Error(`Unknown formatter: ${name}`);
     }
 }
+/**
+ * Gets a list of available formatter names
+ * @returns Array of formatter names
+ */
 export function getAvailableFormatters() {
     return ['default', 'json', 'compact', 'github-actions', 'sarif'];
 }