/**
 * CLI-versus-proxy version skew (#2701, #3464).
 *
 * The reported failure: `ocx` on PATH is an older install than the running proxy, so its
 * help describes commands the proxy does not have and its output describes a different
 * build. Nothing surfaced that, because the CLI never compared the two.
 *
 * Kept in its own module rather than inside `status.ts` so `doctor` can reuse the exact
 * comparison instead of reimplementing it -- two diagnostics disagreeing about whether an
 * install is stale would be worse than neither reporting it.
 */
import { compareStrictSemver, parseStrictSemver } from "../lib/strict-semver";

/** Placeholder versions that mean "unknown", not "different". */
const PLACEHOLDERS = new Set(["unknown", "0.0.0"]);

/**
 * Which side of the comparison runs newer, so a consumer does not reparse the warning to
 * find the direction. `"match"` is a real, non-placeholder equality; placeholders and a
 * missing proxy version are `"unknown"`, and `"incomparable"` covers versions that
 * differ but do not order under strict semver. The desktop shell reads this field to
 * keep a takeover from silently downgrading a newer runtime.
 */
export type VersionRelation =
  | "match"
  | "cli-newer"
  | "proxy-newer"
  | "incomparable"
  | "unknown";

export interface VersionSkew {
  readonly cliVersion: string;
  /** Version the live proxy reported, or null when nothing is live or it reported none. */
  readonly proxyVersion: string | null;
  readonly skewed: boolean;
  readonly relation: VersionRelation;
  /** Operator-facing explanation; null when there is nothing to report. */
  readonly warning: string | null;
}

/** Suppressed comparisons are not confirmed matches, even when both placeholders agree. */
export function isConfirmedVersionMatch(skew: VersionSkew): boolean {
  return skew.proxyVersion === skew.cliVersion && !PLACEHOLDERS.has(skew.cliVersion);
}

/**
 * Compare the running CLI against the live proxy.
 *
 * Suppressed rather than reported when either side is a placeholder. `packageVersion()`
 * answers `"unknown"` when `package.json` carries no string version, and the server's
 * `VERSION` falls back to `"0.0.0"` when it cannot resolve its own package -- comparing
 * against either would report skew that says nothing about the install. A false stale-CLI
 * warning would send an operator to reinstall a healthy setup.
 */
export function computeVersionSkew(cliVersion: string, proxyVersion: string | undefined): VersionSkew {
  const proxy = proxyVersion ?? null;
  if (proxy === null || PLACEHOLDERS.has(proxy) || PLACEHOLDERS.has(cliVersion)) {
    return { cliVersion, proxyVersion: proxy, skewed: false, relation: "unknown", warning: null };
  }
  if (proxy === cliVersion) {
    return { cliVersion, proxyVersion: proxy, skewed: false, relation: "match", warning: null };
  }
  const cliSemver = parseStrictSemver(cliVersion);
  const proxySemver = parseStrictSemver(proxy);
  const order = cliSemver && proxySemver ? compareStrictSemver(cliSemver, proxySemver) : 0;
  const relation: VersionRelation =
    order > 0 ? "cli-newer" : order < 0 ? "proxy-newer" : "incomparable";
  const advice = order > 0
    ? "the running proxy is older than this CLI. Restart the proxy using the intended current installation. "
      // `restart`, not `repair`: a version skew leaves the service DEFINITION unchanged, and
      // repair reloads only when something changed, so it would no-op and keep the old
      // process serving (#4249).
      + "For a background service, run ocx service restart (repair reloads only a changed definition)."
    : order < 0
      ? "this ocx on PATH is older than the running proxy. Upgrade the CLI or resolve PATH to the intended installation."
      : "the versions differ, but neither can be identified as older. Check which installations the CLI and proxy use.";
  return {
    cliVersion,
    proxyVersion: proxy,
    skewed: true,
    relation,
    warning: `CLI ${cliVersion} does not match the running proxy ${proxy} — ${advice}`,
  };
}
