/**
 * Soft-accept an instrumentation target. Never throws.
 * - `null` / `undefined` → `console.warn` and return `undefined`
 * - fails `isValid` → `console.error` and return `undefined`
 */
export function acceptInstrumentTarget<T>(
    kind: string,
    value: unknown,
    isValid: (value: unknown) => value is T
): T | undefined {
    if (value == null) {
        // eslint-disable-next-line no-console -- soft-skip missing host wiring
        console.warn(`[journey] instrument${kind}: skipped — missing`);
        return undefined;
    }
    if (!isValid(value)) {
        // eslint-disable-next-line no-console -- soft-skip invalid host wiring
        console.error(
            `[journey] instrument${kind}: skipped — invalid shape (${describeTarget(value)})`
        );
        return undefined;
    }
    return value;
}

function describeTarget(value: unknown): string {
    const kind = typeof value;
    if (value != null && (kind === 'object' || kind === 'function')) {
        const name = (value as { constructor?: { name?: string } }).constructor?.name;
        if (typeof name === 'string' && name !== '' && name !== 'Object') {
            return `${kind} ${name}`;
        }
    }
    return kind;
}