// sources.mjs — where a clip's media comes from when it is ALREADY ON DISK.
//
// A render needs a few seconds of a source around each clip. Those seconds are
// usually somewhere local already, in one of three places, and fetching them
// again is the one expensive thing a build does. So before anything asks the
// network, the build asks this module, in this order:
//
//   1. raw-cache      the build's own `out/clips-raw/<video>_<from>-<to>.mp4`
//   2. corpus-window  the editor's window cache,
//                     `channels/<slug>/data/<id>/clips/<from>-<to>.<ext>`
//   3. saved-video    the whole source container: the saved-video store's
//                     pointer (`data/<id>/saved-video.json` -> `<dir>/<file>`),
//                     else a `data/<id>/source-media.<ext>` not yet moved there.
//                     It is the window [0, its probed duration].
//   4. audio          `data/<id>/audio.<ext>`: the recording's SOUND alone, the
//                     window [0, its probed duration]. The build draws a poster
//                     where the picture would be.
//
// THE AUDIO TIER IS ASKED ONLY WHEN THE CALLER SAYS SO (`audio: true`), and
// `audioUse` below is the one rule for when, and under which name:
//   "audio-only"      the clip has no picture to fetch -- `audioOnly: true`,
//                     `render.preferLocalAudio`, a record whose platform
//                     carries none, or a record with no page to fetch from.
//                     Asked before the network: it is what plays a podcast.
//   "audio-fallback"  the clip SHOULD have a picture, the build may not fetch
//                     one (`--no-network`, `--skip-fetch`), and the operator
//                     said `--audio-fallback`. Without that flag such a clip is
//                     a miss, so `--no-network` still proves every picture is
//                     on disk.
// Being last, it never beats a picture already on disk. Many transcribed
// videos keep an `audio.mp3`, so without the rule a cut would quietly lose its
// pictures to it.
//
// A window qualifies only if it holds the REQUESTED span whole -- the clip plus
// the build's fetch pad -- to WIN_EPS. Within a tier the tightest wins (the
// build decodes what it is handed); across tiers the order above wins, so a
// file this project already cut from keeps being the one it cuts from.
//
// The tiers are a list, not a chain of ifs: each is `{kind, windows(ctx)}`, and
// the next kind of local source is one more entry. A tier is only listed when
// every tier before it missed, so the saved-video probe (an ffprobe, perhaps on
// a platter) is paid for only by a clip nothing nearer could serve.
//
// A file in `data/<id>/` may be a RELATIVE symlink into `media/`, which may be
// an absolute symlink to another drive. Every candidate is `stat`ed through its
// links before it is returned, and a dangling one -- an unmounted drive -- is
// "not here", never an error: the build falls through to the next tier.
//
// THE CORPUS HALF IS COMMON'S (common/lib/evidenceClip.mjs): tiers 2-4, the
// window predicates and the probe live there, once, because the report-site
// prepare step (common/lib/evidenceClip-server.ts) asks the same question of
// the same disk and must get the same answer. This module adds the build's own
// raw cache in front of them and re-exports the rest, so every importer here
// keeps its names.
//
// A LEAF. Plain ESM with no imports from build-video.mjs or umtool's lib, so
// the build, the clip bench (lib/projects/report.mjs) and lib/report/raw-cache
// can all import it without a cycle, and so the bench and the render cannot
// disagree about what is local. It never computes a path from the cwd: every
// root arrives as an argument (see umtool/lib/paths.mjs on why that matters to
// the Next build).
import path from "node:path";
import {
  AUDIO_ONLY_PLATFORMS,
  CORPUS_TIERS,
  WINDOW_RE,
  listNames,
  present,
  resolveFromTiers,
  windowContains,
  tightestContaining,
  ffprobeSource,
} from "yt-dlp-transcript-common/lib/evidenceClip.mjs";

export {
  AUDIO_ONLY_PLATFORMS,
  AUDIO_PREFERENCE,
  CORPUS_WINDOW_EXTS,
  SAVED_VIDEO_POINTER,
  WIN_EPS,
  audioFilesOf,
  corpusClipsDir,
  ffprobeSource,
  present,
  readSavedVideoPointer,
  tightestContaining,
  videoDirOf,
  wholeContainersOf,
  windowContains,
  windowsFromBareNames,
} from "yt-dlp-transcript-common/lib/evidenceClip.mjs";

/** The source kinds, in the order they are consulted. */
export const SOURCE_KINDS = ["raw-cache", ...CORPUS_TIERS.map((t) => t.kind)];

/**
 * May the audio tier serve this clip, and as what? (See the note at the top.)
 *
 * @param {{ entry?: any, meta?: { platform?: string|null, webpageUrl?: string|null }|null,
 *   render?: any, network?: boolean, fallback?: boolean }} args
 *   `network` is whether this build may fetch at all; `fallback` is
 *   `--audio-fallback`; `meta` is the record, when it has been read (without
 *   it, only the entry and render can say).
 * @returns {"audio-only" | "audio-fallback" | null}
 */
export function audioUse({ entry = null, meta = null, render = null, network = true, fallback = false } = {}) {
  if (entry?.audioOnly === true || render?.preferLocalAudio === true) return "audio-only";
  if (AUDIO_ONLY_PLATFORMS.has(String(meta?.platform ?? "").toLowerCase())) return "audio-only";
  // A record with no page has nothing a fetch could get.
  if (meta != null && !meta.webpageUrl) return "audio-only";
  // A picture exists somewhere: its sound stands in only when asked to.
  if (!network && fallback) return "audio-fallback";
  return null;
}

/** audioUse's yes or no: should the audio tier be consulted at all? */
export const audioAllowed = (args = {}) => audioUse(args) !== null;

// ---- the build's raw cache (tier 1) ----------------------------------------
// A raw clip's window is IN ITS NAME, which makes the file immutable and the
// cache content-addressed. TWO DECIMALS, always: the name is a function of the
// numbers and nothing else.

/** The raw-cache file name for a window of `video`. The build's cache key. */
export function rawWindowName(video, from, to) {
  return `${video}_${from.toFixed(2)}-${to.toFixed(2)}.mp4`;
}

/** A directory listing, or [] for a directory that is not there. */
export const listRawNames = listNames;

/** The windows THIS video's files hold, parsed out of a clips-raw listing. */
export function windowsFromNames(names, rawDir, video) {
  const prefix = `${video}_`;
  const out = [];
  for (const name of names) {
    if (!name.startsWith(prefix) || !name.endsWith(".mp4")) continue;
    // The remainder must be exactly `a-b`, which is what stops a video id that
    // is a prefix of another (or one containing `_`) from claiming its files.
    const m = WINDOW_RE.exec(name.slice(prefix.length, -4));
    if (!m) continue;
    out.push({ name, path: path.join(/* turbopackIgnore: true */ rawDir, name), from: Number(m[1]), to: Number(m[2]) });
  }
  return out;
}

export async function cachedWindowsFor(rawDir, video) {
  return windowsFromNames(await listRawNames(rawDir), rawDir, video);
}

/** The tightest cached file containing [from, to], or null. */
export async function findContainingWindow(rawDir, video, from, to) {
  return tightestContaining(await cachedWindowsFor(rawDir, video), from, to);
}

// ---- the tiers ---------------------------------------------------------------
// Each lists a video's candidate windows `{name, path, from, to, height?}` for
// one context `{video, slug, rawDir, channelsDir, probe}`. A tier that cannot
// apply (no rawDir, no channelsDir or slug) lists nothing.

async function rawCacheWindows({ video, rawDir }) {
  if (!rawDir) return [];
  return cachedWindowsFor(rawDir, video);
}

// `audio: true` marks a tier consulted only when the caller allows it.
export const TIERS = [{ kind: "raw-cache", windows: rawCacheWindows }, ...CORPUS_TIERS];

/**
 * The local source for one span of one video, or null when nothing on disk
 * holds it and only a fetch would.
 *
 * @param {{ video: string, slug?: string|null, from: number, to: number }} want
 *   `from`/`to` are the PADDED span -- what the build would otherwise fetch.
 * @param {{ rawDir?: string|null, channelsDir?: string|null, exact?: boolean,
 *   probe?: (file: string) => Promise<{duration: number, height?: number}|null>,
 *   kinds?: string[] }} [config]
 *   `exact` (`--no-reuse`) accepts only the raw-cache file named for exactly
 *   this span. `kinds` narrows the tiers consulted (default: all, in order).
 *   `audio` admits the audio tier (default false; see `audioUse`).
 * @returns {Promise<null | { kind: string, path: string, name: string,
 *   windowStart: number, windowEnd: number, height?: number }>}
 */
export async function resolveLocalSource(want, config = {}) {
  const { video, slug = null, from, to } = want;
  const { rawDir = null, channelsDir = null, exact = false, probe, kinds = null, audio = false } = config;
  if (!video || !Number.isFinite(from) || !Number.isFinite(to)) return null;

  if (exact) {
    if (rawDir) {
      const name = rawWindowName(video, from, to);
      const p = path.join(/* turbopackIgnore: true */ rawDir, name);
      if (await present(p)) return { kind: "raw-cache", path: p, name, windowStart: from, windowEnd: to };
    }
    // `--no-reuse` re-cuts no cached window, but the sound is not one.
    if (!audio) return null;
  }

  // The raw cache's EXACT name first, as it always was; then tightest.
  const exactName = rawWindowName(video, from, to);
  return resolveFromTiers(TIERS, { video, slug, rawDir, channelsDir, probe }, from, to, {
    allow: (tier) => (!kinds || kinds.includes(tier.kind)) && (tier.audio ? audio : !exact),
    preferName: (tier) => (tier.kind === "raw-cache" ? exactName : null),
  });
}

/**
 * Every window of a video OUTSIDE the project -- the corpus tiers -- each
 * tagged with its `kind` and checked to be there. What the clip bench folds
 * into its view of the raw cache, so the bench's "fetched" and the render's
 * "local" are the same set.
 *
 * `probe` decides a whole container's span. The bench passes a cheap one (the
 * cue doc's duration) and is asked only for a video that has a container.
 *
 * Not the audio tier: many transcribed videos keep their sound, and a
 * bench that called each of those "fetched" would never offer a fetch.
 */
export async function corpusWindowsOf({ video, slug, channelsDir, probe = ffprobeSource }) {
  const ctx = { video, slug, channelsDir, probe };
  const out = [];
  for (const tier of CORPUS_TIERS) {
    if (tier.audio) continue;
    for (const w of await tier.windows(ctx)) {
      if (await present(w.path)) out.push({ ...w, kind: tier.kind });
    }
  }
  return out;
}

// ---- which channels tree -------------------------------------------------------

/** The conventional name make-shadow-channels.sh builds. */
export const SHADOW_CHANNELS = ".shadow-channels";

/**
 * Which channels directory a project reads: `provenance.channelsDir` (resolved
 * against the project dir), else a `.shadow-channels/` the project built, else
 * `fallback` (the global corpus). The bench and the render both ask this, so
 * they look for local media in the same tree.
 */
export function channelsDirFor(dir, manifest, { shadowExists = false, fallback = null } = {}) {
  const declared = manifest?.provenance?.channelsDir;
  if (declared) return path.resolve(/* turbopackIgnore: true */ dir, declared);
  if (shadowExists) return path.join(/* turbopackIgnore: true */ dir, SHADOW_CHANNELS);
  return fallback;
}