/**
 * apiVersion compatibility (ADR 0008: "incompatible plugins are refused at
 * install time"). The manifest's `apiVersion` is a single major version string
 * (e.g. `"1"`); the host declares the inclusive range of majors it supports and
 * refuses anything outside it.
 */

/** The highest plugin API major this SDK release implements. */
export const HOST_API_VERSION = 1;

/** Inclusive range of plugin API majors a host accepts. */
export interface ApiVersionRange {
  min: number;
  max: number;
}

/** The default range: everything from major 1 up to the current host version. */
export const DEFAULT_API_VERSION_RANGE: ApiVersionRange = { min: 1, max: HOST_API_VERSION };

export interface ApiVersionCheck {
  compatible: boolean;
  /** The parsed major, or `null` when `apiVersion` was not a valid version. */
  version: number | null;
  /** Present only when incompatible: a human-readable, actionable reason. */
  reason?: string;
}

/**
 * Checks a manifest `apiVersion` against the host's supported range. Returns a
 * structured result so callers can surface the reason to the Site Admin rather
 * than a bare boolean.
 */
export function checkApiVersion(
  apiVersion: string,
  range: ApiVersionRange = DEFAULT_API_VERSION_RANGE,
): ApiVersionCheck {
  if (!/^\d+$/.test(apiVersion)) {
    return {
      compatible: false,
      version: null,
      reason: `apiVersion "${apiVersion}" is not a whole-number major version`,
    };
  }
  const version = Number.parseInt(apiVersion, 10);
  if (version < range.min || version > range.max) {
    return {
      compatible: false,
      version,
      reason: `plugin apiVersion ${version} is outside the supported range ${range.min}–${range.max}`,
    };
  }
  return { compatible: true, version };
}

/** Convenience boolean form of {@link checkApiVersion}. */
export function isApiVersionSupported(
  apiVersion: string,
  range: ApiVersionRange = DEFAULT_API_VERSION_RANGE,
): boolean {
  return checkApiVersion(apiVersion, range).compatible;
}