validate.ts

import { ErrorObject } from 'ajv/dist/2020.js';
import { Spectral, ISpectralDiagnostic, RulesetDefinition } from '@stoplight/spectral-core';

import validationRulesForPattern from '../../spectral/rules-pattern';
import validationRulesForArchitecture from '../../spectral/rules-architecture';
import validationRulesForTimeline from '../../spectral/rules-timeline';
import { DiagnosticSeverity } from '@stoplight/types';
import { initLogger, Logger } from '../../logger.js';
import { ValidationOutput, ValidationOutcome } from './validation.output.js';
import { SpectralResult } from './spectral.result.js';
import createJUnitReport from './output-formats/junit-output.js';
import prettyFormat from './output-formats/pretty-output.js';
import { SchemaDirectory } from '../../schema-directory.js';
import { JsonSchemaValidator } from './json-schema-validator.js';
import { selectChoices, CalmChoice } from '../generate/components/options.js';

let logger: Logger; // defined later at startup

export type ValidateOutputFormat = 'json' | 'junit' | 'pretty';

export interface ValidationDocumentContext {
    id: string;
    label?: string;
    filePath?: string;
    lines?: string[];
}

export interface ValidationFormattingOptions {
    documents?: Record<string, ValidationDocumentContext>;
}

/**
 * TODO - move this out of shared and into the CLI - this is process-management code.
 * Given a validation outcome - exit from the process gracefully with an exit code we conrol.
 * @param validationOutcome Outcome to process from call to validate.
 * @param failOnWarnings If true, the process will exit with a non-zero exit code for warnings as well as errors.
 */
export function exitBasedOffOfValidationOutcome(validationOutcome: ValidationOutcome, failOnWarnings: boolean) {
    if (validationOutcome.hasErrors) {
        process.exit(1);
    }
    if (validationOutcome.hasWarnings && failOnWarnings) {
        process.exit(1);
    }
    process.exit(0);
}

export type OutputFormat = 'junit' | 'json' | 'pretty'

export function formatOutput(
    validationOutcome: ValidationOutcome,
    format: OutputFormat,
    options?: ValidationFormattingOptions
): string {
    logger.info(`Formatting output as ${format}`);
    switch (format) {
    case 'junit': {
        const spectralRuleNames = extractSpectralRuleNames();
        return createJUnitReport(validationOutcome, spectralRuleNames);
    }
    case 'pretty':
        return prettyFormat(validationOutcome, options);
    case 'json':
        return prettifyJson(validationOutcome);
    }
}


async function runSpectralValidations(
    schema: string,
    spectralRuleset: RulesetDefinition,
    source: string
): Promise<SpectralResult> {
    let errors = false;
    let warnings = false;
    let spectralIssues: ValidationOutput[] = [];
    const spectral = new Spectral();

    spectral.setRuleset(spectralRuleset);
    const issues = await spectral.run(schema);

    if (issues && issues.length > 0) {
        logger.debug(`Spectral raw output: ${prettifyJson(issues)}`);
        sortSpectralIssueBySeverity(issues);
        spectralIssues = convertSpectralDiagnosticToValidationOutputs(issues, source);
        if (issues.filter(issue => issue.severity === 0).length > 0) {
            logger.debug('Spectral output contains errors');
            errors = true;
        }
        if (issues.filter(issue => issue.severity === 1).length > 0) {
            logger.debug('Spectral output contains warnings');
            warnings = true;
        }
    }
    return new SpectralResult(warnings, errors, spectralIssues);
}


/**
 * Validation - with simple input parameters and output validation outcomes.
 * @param architecture The architecture as a JS object, or undefined if not provided
 * @param patternOrSchema The pattern (or schema) as a JS object, or undefined if not provided
 * @param timeline The timeline as a JS object, or undefined if not provided
 * @param schemaDirectory SchemaDirectory instance for schema resolution
 * @param debug Whether to log at debug level
 * @returns Validation report
 */
export async function validate(
    architecture: object | undefined,
    patternOrSchema: object | undefined,
    timeline: object | undefined,
    schemaDirectory?: SchemaDirectory,
    debug: boolean = false
): Promise<ValidationOutcome> {
    logger = initLogger(debug, 'calm-validate');

    try {
        if (timeline) {
            if (architecture) {
                throw new Error('You cannot provide an architecture when validating a timeline');
            }
            if (!patternOrSchema) {
                throw new Error('You must provide a schema to validate the timeline against, or the timeline must reference it internally');
            }
            // It is acceptable, in fact desired, for `patternOrSchema` to be set, and be the CALM timeline schema.
            return await validateTimeline(timeline, patternOrSchema, schemaDirectory, debug);
        } else if (architecture && patternOrSchema) {
            // Note that patternOrSchema may be a CALM pattern, or might be the CALM core schema.
            // The caller is responsible for honoring the architecture's `$schema`, or using an explicitly provided pattern.
            // In either case, we validate the architecture against it.
            return await validateArchitectureAgainstPattern(architecture, patternOrSchema, schemaDirectory, debug);
        } else if (patternOrSchema) {
            // `patternOrSchema` should really be a CALM pattern in this case.
            return await validatePatternOnly(patternOrSchema, schemaDirectory, debug);
        } else if (architecture) {
            return await validateArchitectureOnly(architecture);
        } else {
            logger.debug('You must provide an architecture, a pattern, or a timeline');
            throw new Error('You must provide an architecture, a pattern, or a timeline');
        }
    } catch (error) {
        logger.error('An error occurred:' + error);
        throw error;
    }
}

/**
 * Run the spectral rules for the pattern and the architecture, and then compile the pattern and validate the architecture against it.
 *
 * @param architecture - the architecture to validate.
 * @param pattern - the pattern to validate against.
 * @param schemaDirectory - the SchemaDirectory instance to use for schema resolution.
 * @param debug - the flag to enable debug logging.
 * @returns the validation outcome with the results of the spectral and json schema validations.
 */
async function validateArchitectureAgainstPattern(architecture: object, pattern: object, schemaDirectory: SchemaDirectory, debug: boolean): Promise<ValidationOutcome> {
    const spectralResultForPattern: SpectralResult = await runSpectralValidations(stripRefs(pattern), validationRulesForPattern, 'pattern');
    const spectralResultForArchitecture: SpectralResult = await runSpectralValidations(JSON.stringify(architecture), validationRulesForArchitecture, 'architecture');

    const spectralResult = mergeSpectralResults(spectralResultForPattern, spectralResultForArchitecture);

    let errors = spectralResult.errors;
    const warnings = spectralResult.warnings;

    const patternResolved = applyArchitectureOptionsToPattern(architecture, pattern, debug);

    let jsonSchemaValidations = [];
    let jsonSchemaValidator: JsonSchemaValidator;
    try {
        jsonSchemaValidator = new JsonSchemaValidator(schemaDirectory, patternResolved, debug);
        await jsonSchemaValidator.initialize();
    } catch (error) {
        const errorMessage = toErrorMessage(error);
        logger.error(`JSON Schema compilation failed: ${errorMessage}`);
        jsonSchemaValidations = [
            new ValidationOutput('json-schema', 'error', errorMessage, '/', undefined, undefined, undefined, undefined, undefined, 'pattern')
        ];
        return new ValidationOutcome(jsonSchemaValidations, spectralResult.spectralIssues, true, warnings);
    }

    const schemaErrors = jsonSchemaValidator.validate(architecture);
    if (schemaErrors.length > 0) {
        logger.debug(`JSON Schema validation raw output: ${prettifyJson(schemaErrors)}`);
        errors = true;
        jsonSchemaValidations = convertJsonSchemaIssuesToValidationOutputs(schemaErrors, 'architecture');
    }

    return new ValidationOutcome(jsonSchemaValidations, spectralResult.spectralIssues, errors, warnings);
}


/**
 * Run validations for the case where only the pattern is provided.
 * This essentially runs the spectral validations and tries to compile the pattern.
 *
 * @param pattern - the pattern to validate.
 * @param schemaDirectory - the SchemaDirectory instance to use for schema resolution.
 * @param debug - the flag to enable debug logging.
 * @returns the validation outcome with the results of the spectral validation and the pattern compilation.
 */
async function validatePatternOnly(pattern: object, schemaDirectory: SchemaDirectory, debug: boolean): Promise<ValidationOutcome> {
    logger.debug('Architecture was not provided, only the Pattern Schema will be validated');
    const spectralValidationResults: SpectralResult = await runSpectralValidations(stripRefs(pattern), validationRulesForPattern, 'pattern');

    let errors = spectralValidationResults.errors;
    const warnings = spectralValidationResults.warnings;
    const jsonSchemaErrors = [];

    try {
        // Compile pattern as a schema to check if it's valid
        const jsonSchemaValidator = new JsonSchemaValidator(schemaDirectory, pattern, debug);
        await jsonSchemaValidator.initialize();
    } catch (error) {
        errors = true;
        jsonSchemaErrors.push(new ValidationOutput('json-schema', 'error', toErrorMessage(error), '/', undefined, undefined, undefined, undefined, undefined, 'pattern'));
    }

    return new ValidationOutcome(jsonSchemaErrors, spectralValidationResults.spectralIssues, errors, warnings);// added spectral to return object
}

/**
 * Run the spectral validations for the case where only the architecture is provided.
 * Note that if only the architecture is provided, the CLI tool will attempt to validate the architecture against its specified CALM schema.
 * i.e. the validateArchitectureAgainstPattern method will be called instead of this method.
 * 
 * @param architecture - The architecture, as a JS object.
 * @returns the validation outcome with the results of the spectral validation 
 **/
async function validateArchitectureOnly(architecture: object): Promise<ValidationOutcome> {
    logger.debug('Pattern was not provided, validating Architecture against its specified CALM schema');

    const spectralResultForArchitecture: SpectralResult = await runSpectralValidations(JSON.stringify(architecture), validationRulesForArchitecture, 'architecture');

    const jsonSchemaValidations = [];
    const errors = spectralResultForArchitecture.errors;
    const warnings = spectralResultForArchitecture.warnings;

    logger.debug(`Returning validation outcome with ${jsonSchemaValidations.length} JSON schema validations, errors: ${errors}`);
    return new ValidationOutcome(jsonSchemaValidations, spectralResultForArchitecture.spectralIssues, errors, warnings);
}

/**
 * Run validations for a timeline.
 * This essentially runs the spectral validations and tries to compile the timeline.
 *
 * @param timeline - the timeline to validate.
 * @param schema - the schema to validate against. This should be the CALM timeline schema.
 * @param schemaDirectory - the SchemaDirectory instance to use for schema resolution.
 * @param debug - the flag to enable debug logging.
 * @returns the validation outcome with the results of the spectral validation and the timeline compilation.
 */
async function validateTimeline(timeline: object, schema: object, schemaDirectory: SchemaDirectory, debug: boolean): Promise<ValidationOutcome> {
    logger.debug('Timeline will be validated');
    const spectralValidationResults: SpectralResult = await runSpectralValidations(stripRefs(timeline), validationRulesForTimeline, 'timeline');

    let errors = spectralValidationResults.errors;
    const warnings = spectralValidationResults.warnings;

    const jsonSchemaValidator = new JsonSchemaValidator(schemaDirectory, schema, debug);
    await jsonSchemaValidator.initialize();

    let jsonSchemaValidations = [];

    const schemaErrors = jsonSchemaValidator.validate(timeline);
    if (schemaErrors.length > 0) {
        logger.debug(`JSON Schema validation raw output: ${prettifyJson(schemaErrors)}`);
        errors = true;
        jsonSchemaValidations = convertJsonSchemaIssuesToValidationOutputs(schemaErrors, 'timeline');
    }

    return new ValidationOutcome(jsonSchemaValidations, spectralValidationResults.spectralIssues, errors, warnings);
}

/**
 * If a pattern contains objects, we need to apply the chosen options recorded
 * in the architecture to the pattern to produce a JSON schema pattern that can
 * be used for validation.
 * @param architecture Architecture which may contain options.
 * @param pattern Pattern which may contain options.
 * @param debug - the flag to enable debug logging.
 * @returns Pattern with options applied and flattened.
 */
export function applyArchitectureOptionsToPattern(architecture: object, pattern: object, debug: boolean): object {

    const choices: CalmChoice[] = extractChoicesFromArchitecture(architecture);
    if (choices.length === 0) {
        return pattern;
    }

    return selectChoices(pattern, choices, debug);
}

export function extractChoicesFromArchitecture(architecture: object): CalmChoice[] {
    if (!architecture || !Object.prototype.hasOwnProperty.call(architecture, 'relationships')) {
        return [];
    }

    return architecture['relationships']
        .filter((rel: object) => rel['relationship-type'] && Object.prototype.hasOwnProperty.call(rel['relationship-type'], 'options'))
        .map((rel: object) => rel['relationship-type']['options'][0])
        .map((rel: object) => ({
            description: rel['description'],
            nodes: rel['nodes'] || [],
            relationships: rel['relationships'] || []
        }));
}

function extractSpectralRuleNames(): string[] {
    const architectureRuleNames = getRuleNamesFromRuleset(validationRulesForArchitecture);
    const patternRuleNames = getRuleNamesFromRuleset(validationRulesForPattern);
    return architectureRuleNames.concat(patternRuleNames);
}

function getRuleNamesFromRuleset(ruleset: RulesetDefinition): string[] {
    return Object.keys((ruleset as { rules: Record<string, unknown> }).rules);
}

function prettifyJson(json) {
    return JSON.stringify(json, null, 4);
}

function toErrorMessage(error: unknown): string {
    if (error instanceof Error) {
        return error.message;
    }
    if (typeof error === 'string') {
        return error;
    }
    try {
        return JSON.stringify(error);
    } catch {
        return 'Unknown error';
    }
}

export function stripRefs(obj: object): string {
    return JSON.stringify(obj).replaceAll('$ref', 'ref');
}

export function sortSpectralIssueBySeverity(issues: ISpectralDiagnostic[]): void {
    issues.sort((issue1: ISpectralDiagnostic, issue2: ISpectralDiagnostic) =>
        issue1.severity.valueOf() - issue2.severity.valueOf()
    );
}

export function convertJsonSchemaIssuesToValidationOutputs(jsonSchemaIssues: ErrorObject[], source: string): ValidationOutput[] {
    return jsonSchemaIssues.map(issue => {
        const rawPath = issue.instancePath ?? '';
        const path = rawPath === '' ? '/' : rawPath;
        return new ValidationOutput(
            'json-schema',
            'error',
            appendExpected(issue),
            path,
            issue.schemaPath,
            undefined,
            undefined,
            undefined,
            undefined,
            source
        );
    });
}

export function convertSpectralDiagnosticToValidationOutputs(spectralIssues: ISpectralDiagnostic[], source: string): ValidationOutput[] {
    const validationOutput: ValidationOutput[] = [];

    spectralIssues.forEach(issue => {
        const startRange = issue.range.start;
        const endRange = issue.range.end;
        const formattedIssue = new ValidationOutput(
            issue.code,
            getSeverity(issue.severity),
            issue.message,
            '/' + issue.path.join('/'),
            '',
            startRange.line,
            endRange.line,
            startRange.character,
            endRange.character,
            source
        );
        validationOutput.push(formattedIssue);
    });

    return validationOutput;
}


function getSeverity(spectralSeverity: DiagnosticSeverity): string {
    switch (spectralSeverity) {
    case 0:
        return 'error';
    case 1:
        return 'warning';
    case 2:
        return 'info';
    case 3:
        return 'hint';
    default:
        throw Error('The spectralSeverity does not match the known values');
    }
}

function appendExpected(issue: ErrorObject): string {
    if (!issue || !issue.params) {
        return issue?.message ?? '';
    }

    const params = issue.params as Record<string, unknown>;

    // const keyword: prefer params.allowedValue, fall back to schema (AJV sets schema to the const value)
    if (issue.keyword === 'const') {
        const allowed = 'allowedValue' in params ? params['allowedValue'] : (issue as unknown as { schema?: unknown }).schema;
        if (allowed !== undefined) {
            return `${issue.message} (expected ${safeStringify(allowed)})`;
        }
    }

    // enum keyword: prefer params.allowedValues, fall back to schema array
    if (issue.keyword === 'enum') {
        const allowedValues = 'allowedValues' in params ? params['allowedValues'] : (issue as unknown as { schema?: unknown }).schema;
        if (Array.isArray(allowedValues)) {
            return `${issue.message} (expected one of ${safeStringify(allowedValues)})`;
        }
    }

    return issue.message ?? '';
}

function safeStringify(value: unknown): string {
    try {
        return JSON.stringify(value);
    } catch (_) {
        return String(value);
    }
}

/**
 * Merge the results from two Spectral validations together, combining any errors/warnings.
 * @param spectralResultPattern Spectral results from the pattern validation
 * @param spectralResultArchitecture Spectral results from the architecture validation
 * @returns A new SpectralResult with the error/warning status propagated and the results concatenated.
 */
function mergeSpectralResults(spectralResultPattern: SpectralResult, spectralResultArchitecture: SpectralResult): SpectralResult {
    const errors: boolean = spectralResultPattern.errors || spectralResultArchitecture.errors;
    const warnings: boolean = spectralResultPattern.warnings || spectralResultArchitecture.warnings;
    const spectralValidations = spectralResultPattern.spectralIssues.concat(spectralResultArchitecture.spectralIssues);
    return new SpectralResult(warnings, errors, spectralValidations);
}