import {
    defineCodes,
    SuaveplanError,
    type SuaveplanErrorOptions,
} from "@suaveplan/error";

/**
 * Stable error-code registry for `@suaveplan/audio-analysis-spectrum`.
 * `defineCodes` namespaces the string values as `AUDIO_ANALYSIS_SPECTRUM.<REASON>`.
 */
export const AUDIO_ANALYSIS_SPECTRUM_CODES = defineCodes(
    "AUDIO_ANALYSIS_SPECTRUM",
    ["INVALID_OPTIONS", "INVALID_FRAME", "ABORTED"] as const
);

export type AudioAnalysisSpectrumErrorCode =
    (typeof AUDIO_ANALYSIS_SPECTRUM_CODES)[keyof typeof AUDIO_ANALYSIS_SPECTRUM_CODES];

export interface AudioAnalysisSpectrumErrorMetadata {
    readonly description: string;
    readonly severity: "warning" | "error";
}

export const AUDIO_ANALYSIS_SPECTRUM_ERROR_METADATA: Readonly<
    Record<AudioAnalysisSpectrumErrorCode, AudioAnalysisSpectrumErrorMetadata>
> = Object.freeze({
    [AUDIO_ANALYSIS_SPECTRUM_CODES.INVALID_OPTIONS]: {
        description:
            "A public options object failed Zod boundary validation. The Zod `issues` array is attached on `error.context.issues`.",
        severity: "error",
    },
    [AUDIO_ANALYSIS_SPECTRUM_CODES.INVALID_FRAME]: {
        description:
            "The FFT was asked to transform a frame whose size is not a power of two between 256 and 32768 inclusive. The offending size is on `error.context.frameSize`.",
        severity: "error",
    },
    [AUDIO_ANALYSIS_SPECTRUM_CODES.ABORTED]: {
        description:
            "Analysis was cancelled by an `AbortSignal` before or during the scan. The signal reason, if any, is on `error.context.reason`.",
        severity: "warning",
    },
});

/**
 * Concrete `SuaveplanError` subclass for every fault raised by this package.
 * The base constructor is `protected`; this subclass widens it to `public`
 * while remaining non-trivial via the `category` field, so it constructs
 * without any static-analysis suppression.
 */
export class AudioAnalysisSpectrumError extends SuaveplanError<AudioAnalysisSpectrumErrorCode> {
    public readonly category = "audio-analysis-spectrum" as const;

    public constructor(
        code: AudioAnalysisSpectrumErrorCode,
        messageKey: string,
        options: SuaveplanErrorOptions = {}
    ) {
        super(code, messageKey, options);
        this.name = "AudioAnalysisSpectrumError";
    }
}

/**
 * Idempotent registration hook. Metadata is already frozen and exported for
 * direct lookup; consumers binding code registries to OTel attributes or
 * report-builders can call this once at startup to ensure the registry
 * has been touched.
 */
export function registerAudioAnalysisSpectrumErrorCodes(): void {
    // No-op — registry side-effects are static at module load.
}

registerAudioAnalysisSpectrumErrorCodes();