/**
 * ⟨q-c1af2db3⟩ — WHICH TREE DID THIS VERB JUST READ, AND HOW OLD IS IT?
 *
 * ⛔ THE BUG THIS EXISTS FOR ROUTED THE FLEET. `next_unblocked` reads
 * `docs/QUEUE.md` out of whatever working tree it is handed, and that tree
 * belongs to nobody: its freshness is a property of whoever last worked in it.
 * Measured 2026-09-12 16:36 — the primary checkout sat FOUR commits behind
 * `origin/main`, its `QUEUE.md` had zero hits for a tag committed six minutes
 * earlier, and the verb returned the PRE-EDIT text as `next`.
 *
 * ⛆ AND THE HARM LANDED IN BOTH DIRECTIONS INSIDE TEN MINUTES: a row was ruled
 * un-claimable from an observation that was actually a stale file, and a worker
 * was told to hold on a row that was already split. ⭐ ***A true conclusion
 * reached through an untrue reading is the shape, and here the INSTRUMENT
 * supplied the untrue reading — the answer was well-formed, internally
 * consistent, `accounting.reconciles` was TRUE, and nothing in it said which
 * tree it read.***
 *
 * ⛔⛆⛆ THE TRAP THAT BREAKS THE OBVIOUS FIX, AND IT IS WHY THIS FETCHES:
 *
 *     a checkout that has not fetched CANNOT REPORT that it has not fetched.
 *
 * `git rev-list --left-right --count origin/main...HEAD` in an unfetched clone
 * compares HEAD against a STALE `origin/main` ref and returns `0  0` — *"I am
 * perfectly current"* — while the real remote has moved. Measured: HEAD
 * `1cab5c2`, its own `origin/main` also `1cab5c2`, true `origin/main` `558365d`,
 * three commits behind, reported as ZERO. ⭐⭐ ***A distance of `0` from an
 * unfetched ref and a distance of `0` from a fetched one are BYTE-IDENTICAL and
 * mean opposite things. That distinction is the whole point of this module: the
 * ref is fetched IN THIS CALL, and when the fetch fails the answer is
 * `"unknown"` and never `0`.***
 *
 * ⚠ AND FETCHING IS NOT THE FIX — that is the row's named anti-control.
 * Fetching updates REFS; the verb reads the TREE, which is still stale
 * afterwards. So a fetch only makes the staleness *legible*; the caller must
 * still refuse or flag. This module reports; it never silently repairs, because
 * making someone else's working tree current is a destructive write into a
 * checkout a seat may be mid-work in.
 */
import { execFileSync } from "node:child_process";
import path from "node:path";

export type TreeProvenance = {
  /** The tree actually read, resolved — not the string the caller passed. */
  path: string;
  head: string | null;
  /** The ref the distance is measured against, e.g. `origin/main`. */
  base: string;
  baseSha: string | null;
  /**
   * Commits the tree is behind `base`.
   *
   * ⛔ `"unknown"` WHEN THE REF COULD NOT BE FRESHENED IN THIS CALL. Never `0`
   * in that case: `0` is a claim of currency and an unfetched ref cannot make it.
   */
  behind: number | "unknown";
  /** Whether the ref this distance rests on was freshened in THIS call. */
  fetched: boolean;
  fetchError?: string;
  dirty: boolean | "unknown";
  /** True only when the tree is MEASURABLY behind a ref fetched in this call. */
  stale: boolean;
  /** Present whenever the answer cannot be trusted as current. */
  warning?: string;
};

const run = (repo: string, args: string[]): string | null => {
  try {
    return execFileSync("git", args, {
      cwd: repo,
      encoding: "utf8",
      stdio: ["ignore", "pipe", "ignore"],
      timeout: 20_000,
    }).trim();
  } catch {
    return null;
  }
};

/**
 * What the caller needs to say out loud about the tree it just read.
 *
 * @param repo the working tree a verb was handed
 * @param baseBranch the branch the tree should be current with
 */
export function treeProvenance(repo: string, baseBranch = "main"): TreeProvenance {
  const resolved = run(repo, ["rev-parse", "--show-toplevel"]) ?? path.resolve(repo);
  const base = `origin/${baseBranch}`;
  const head = run(resolved, ["rev-parse", "HEAD"]);
  const status = run(resolved, ["status", "--porcelain"]);

  // ⛔ FETCH FIRST, AND THE ORDER IS THE POINT. Every number below is worthless
  // if it rests on a ref the tree last updated at some unknown past moment.
  const fetched = run(resolved, ["fetch", "--quiet", "origin", baseBranch]) !== null;

  const out: TreeProvenance = {
    path: resolved,
    head,
    base,
    baseSha: null,
    behind: "unknown",
    fetched,
    dirty: status === null ? "unknown" : status.length > 0,
    stale: false,
  };

  if (!fetched) {
    out.fetchError = `could not fetch origin/${baseBranch} — the distance cannot be computed`;
    out.warning =
      `TREE FRESHNESS UNKNOWN: ${resolved} could not reach origin/${baseBranch} in this call, so its ` +
      `distance is UNKNOWN rather than 0. A checkout that has not fetched cannot report that it has not ` +
      `fetched — an unfetched ref answers "0 behind" and means nothing.`;
    return out;
  }

  out.baseSha = run(resolved, ["rev-parse", base]);
  const counts = run(resolved, ["rev-list", "--left-right", "--count", `${base}...HEAD`]);
  const behind = counts ? Number(counts.split(/\s+/)[0]) : NaN;
  if (!Number.isFinite(behind)) {
    out.warning = `TREE FRESHNESS UNKNOWN: could not count ${base}...HEAD in ${resolved}.`;
    return out;
  }

  out.behind = behind;
  out.stale = behind > 0;
  if (out.stale) {
    // ⚠ FETCHING DID NOT FIX THE TREE — it only made this sentence possible.
    // The file the verb read is still the old one.
    out.warning =
      `STALE TREE: ${resolved} is ${behind} commit(s) behind ${base} (HEAD ${head?.slice(0, 7)}, ` +
      `${base} ${out.baseSha?.slice(0, 7)}). The answer above was read from THAT tree's files, so a row ` +
      `filed or amended on ${base} since is invisible here and a superseded row can be offered as current. ` +
      `Fetching refreshed the REF, not the working tree.`;
  }
  return out;
}