// ONE DECLARATION PER PER-VIDEO SIDECAR: its filename, its read, its write.
//
// one-core phase 3 slice 4b. Each `<video dir>/<name>.json` sidecar used to be
// a hand-written `X-server.ts` with the same four moves — join the path, read +
// JSON.parse + a shape check inside a try that turns anything wrong into null,
// tmp + rename on write, `rm -f` to clear — copied per file. `sidecar()` is those
// four moves once; an `X-server.ts` now declares its sidecar and keeps only what
// is genuinely its own (a merge, a history append, a derived predicate).
//
//   const s = sidecar(ATTRIBUTION_FILENAME, sidecarField(coerceAttribution), { indent: 0 });
//
// THE NAMING GUARD RUNS AT DECLARATION. `SUB_FILE_RE` (lib/videoStatus.ts)
// claims any `transcript.<x>.<y>` file in a video dir as a subtitle track; a
// sidecar so named would be indexed as a language. `sidecar()` throws when its
// filename matches, and every declaration runs at module load — so a misnamed
// sidecar fails every test that imports it, and the editor's boot, rather than
// quietly becoming a `<x>`-language track. `SIDECAR_FILENAMES` lists every
// declared name for the enumeration test.
//
// READS NEVER THROW. Absent, unreadable, unparseable, or rejected by the
// coercion — all read as null, exactly the rule every sidecar reader had: one
// corrupt sidecar must never fail a channel-wide sweep. A coercion MAY decide a
// parseable-but-malformed file is not null (doNotClean: "any marker at all means
// protected") — that decision is the coercion's, not this module's.
//
// NO FRESHNESS CHECK. The plan named an mtime freshness field; no reader
// consumes one, so none was built (slice 4b record, deviation 1).
//
// SERVER-ONLY (zod, node:fs).

import path from "node:path";
import { rm } from "node:fs/promises";
import { z } from "zod";
import { SUB_FILE_RE } from "./videoStatus";
import {
  readJsonFile,
  writeJsonAtomic,
  type WriteJsonOptions,
} from "./jsonFile-server";

// A sidecar's schema: any parsed JSON in, the record or null out.
export type SidecarSchema<T> = z.ZodType<T | null, unknown>;

// A sidecar FIELD: the existing shape check as a zod schema. It is
// settingsSchema.ts's `settingsField` minus the `.catch`: a settings coercion
// falls back to a default, a sidecar coercion falls back to null ("absent").
export function sidecarField<T>(
  coerce: (value: unknown) => T | null,
): SidecarSchema<T> {
  return z.unknown().transform((value): T | null => coerce(value));
}

export type Sidecar<T> = {
  filename: string;
  path: (videoDir: string) => string;
  load: (videoDir: string) => Promise<T | null>;
  write: (videoDir: string, value: T) => Promise<void>;
  remove: (videoDir: string) => Promise<void>;
};

const declared: string[] = [];

// Every filename declared through `sidecar()` in this process, in declaration
// order. Populated as each `X-server.ts` loads.
export const SIDECAR_FILENAMES: readonly string[] = declared;

export function sidecar<T>(
  filename: string,
  schema: SidecarSchema<T>,
  opts: Pick<WriteJsonOptions, "indent" | "newline"> = {},
): Sidecar<T> {
  if (SUB_FILE_RE.test(filename)) {
    throw new Error(
      `Sidecar "${filename}" matches SUB_FILE_RE (transcript.<x>.<y>) and would be read as a subtitle track — rename it`,
    );
  }
  if (filename.includes("/") || filename.includes(path.sep)) {
    throw new Error(`Sidecar "${filename}" must be a bare filename`);
  }
  if (!declared.includes(filename)) declared.push(filename);
  const at = (videoDir: string) => path.join(videoDir, filename);
  return {
    filename,
    path: at,
    async load(videoDir) {
      const read = await readJsonFile(at(videoDir));
      if (!read.ok) return null;
      try {
        const parsed = schema.safeParse(read.value);
        return parsed.success ? parsed.data : null;
      } catch {
        // A coercion that throws on some input is a bug in the coercion; it
        // still must not fail a sweep.
        return null;
      }
    },
    async write(videoDir, value) {
      await writeJsonAtomic(at(videoDir), value, opts);
    },
    async remove(videoDir) {
      await rm(at(videoDir), { force: true });
    },
  };
}