// Server-side persistence for curated per-video tags. Two source files:
//   - global:   paths.globalTagsFile          (<transcriptsDir>/tags.json)
//   - per-site: sites/<siteId>/tags.json      (siteTagsFile)
// The global file is AUTHORITATIVE for both the vocabulary and the assignments
// (an assignment is a fact about a video, not a presentation choice). The
// per-site file is PRESENTATION — relabel/recolour/reorder/hide — plus
// site-only tags. See common/lib/curatedTags.ts for the pure model, the
// coercion and mergeTagDefs.
//
// **A site-layer RULE never tags a record, so a site layer carries none.**
// Rules are evaluated once at index time over records SHARED by every site that
// carries the channel — there is no per-site record for a per-site hit to live
// in, so a rule written at the site layer could only ever LOOK like it worked.
// The site coercion therefore DROPS rules outright: on READ, so a hand-edited
// sites/<id>/tags.json cannot smuggle one in, and on WRITE, so neither can a
// caller — and mergeTagDefs has no rule branch left to append through. Rules
// bind from transcripts/tags.json alone; promote one there to make it fire.
// This is why the editor offers no site-side rule editor.
//
// Unlike aliasesStore there are NO seeded defaults: a fresh install has no
// tags, and an absent global file reads as an empty config.
//
// ─── The four ops of applyTagAssignments ───
//
// A tag lands on a video two ways: a RULE matched (re-evaluated at every index
// build, never persisted) or the operator PINNED it. So "take this tag off this
// video" has two distinct meanings and they are different ops:
//
//   add        pin the tag, and clear any suppression of it
//   remove     unpin only — a rule that matches this video still tags it
//   suppress   reject the tag: unpin it AND record a suppression, which is the
//              ONLY way a rule-derived tag can be made to go away, because rule
//              hits are not stored anywhere to delete
//   unsuppress clear the rejection (the rule, if any, tags the video again)
//
// The editor's per-video toggle uses add/suppress; the bulk list actions use
// add/remove/suppress; umtool uses add. Every pin AND every suppression records
// provenance (`operator`, `agent:<label>`, `umtool:<project>`), so a later
// reader can always say who claimed what and when.
//
// One call = ONE atomic write of the whole file, however many videos it
// touches. A per-video loop would be N read-modify-writes and could interleave
// with another writer.

import { readFileSync } from "node:fs";
import { writeJsonAtomicSync } from "./jsonFile-server";
import type { Paths } from "./paths";
import { siteTagsFile } from "./site";
import {
  assignmentKey,
  mergeTagDefs,
  sanitizeTagsConfig,
  CURATED_TAGS_VERSION,
  TAG_ID_RE,
  type CuratedTagAssignment,
  type CuratedTagDef,
  type CuratedTagsConfig,
} from "./curatedTags";

// Indented, no trailing newline — these files' historical bytes.
function writeJsonAtomic(filePath: string, value: unknown): void {
  writeJsonAtomicSync(filePath, value, { newline: false, mkdir: true });
}

export function emptyTagsConfig(): CuratedTagsConfig {
  return { version: CURATED_TAGS_VERSION, tags: [], assignments: {} };
}

// The corpus-wide vocabulary + every assignment. Absent/unreadable → empty (a
// fresh install has no tags; there is nothing sensible to seed).
export function readGlobalTags(paths: Paths): CuratedTagsConfig {
  try {
    return sanitizeTagsConfig(
      JSON.parse(readFileSync(paths.globalTagsFile, "utf8")),
    );
  } catch {
    return emptyTagsConfig();
  }
}

export function writeGlobalTags(paths: Paths, config: CuratedTagsConfig): void {
  writeJsonAtomic(paths.globalTagsFile, sanitizeTagsConfig(config));
}

// Per-site presentation overlay + site-only tags. Absent/unreadable → empty
// (no overlay).
//
// Coerced as the SITE layer, on read AND on write: an overlay row that carries
// no label must keep carrying none, or mergeTagDefs would apply an invented one
// and rename the tag on this site. Both directions matter because the file goes
// through sanitize twice — the write, and every read after it.
export function readSiteTags(paths: Paths, siteId: string): CuratedTagsConfig {
  try {
    return sanitizeTagsConfig(
      JSON.parse(readFileSync(siteTagsFile(paths, siteId), "utf8")),
      { layer: "site" },
    );
  } catch {
    return emptyTagsConfig();
  }
}

export function writeSiteTags(
  paths: Paths,
  siteId: string,
  config: CuratedTagsConfig,
): void {
  writeJsonAtomic(
    siteTagsFile(paths, siteId),
    sanitizeTagsConfig(config, { layer: "site" }),
  );
}

// The tag definitions a site actually ships: the corpus vocabulary with the
// site's overlay applied. Read directly by compose-site.ts at build time (the
// source files are available there, like duplicates.json), so there is no
// separate staging step.
//
// Assignments are deliberately NOT part of this: they are global facts and are
// consumed by the index build, not by compose.
export function effectiveSiteTags(
  paths: Paths,
  siteId: string,
): CuratedTagDef[] {
  return mergeTagDefs(readGlobalTags(paths).tags, readSiteTags(paths, siteId).tags);
}

// ─── Assignments ───

export type TagAssignmentOp = "add" | "remove" | "suppress" | "unsuppress";

const OPS: readonly TagAssignmentOp[] = [
  "add",
  "remove",
  "suppress",
  "unsuppress",
];

export type TagVideoRef = { channelSlug: string; id: string };

export type ApplyTagAssignmentsInput = {
  op: TagAssignmentOp;
  tag: string;
  videos: TagVideoRef[];
  // Provenance, recorded on every pin and every suppression this call makes.
  // `operator` | `agent:<label>` | `umtool:<project>` | `rule:<ruleId>`.
  source?: string;
  // ISO-8601 instant; defaults to now. Injectable so tests are deterministic.
  at?: string;
};

export type ApplyTagAssignmentsResult = {
  op: TagAssignmentOp;
  tag: string;
  // Assignment keys whose stored state actually changed — the caller's dirty
  // set. A no-op (pinning what is already pinned) is not reported here.
  changed: string[];
  // Every key the call addressed, changed or not.
  touched: string[];
};

// Order-preserving de-dupe, Set-backed: a bulk "tag selected" can carry
// thousands of refs, and `keys.includes` would make that quadratic.
function dedupeRefs(videos: TagVideoRef[]): string[] {
  const keys: string[] = [];
  const seen = new Set<string>();
  for (const v of videos) {
    if (!v || typeof v.channelSlug !== "string" || typeof v.id !== "string") {
      throw new Error("each video needs a channelSlug and an id");
    }
    const slug = v.channelSlug.trim();
    const id = v.id.trim();
    if (!slug || !id || slug.includes("/") || id.includes("/")) {
      throw new Error(
        `invalid video ref ${JSON.stringify(v)}: channelSlug and id must be non-empty and contain no "/"`,
      );
    }
    const key = assignmentKey(slug, id);
    if (seen.has(key)) continue;
    seen.add(key);
    keys.push(key);
  }
  return keys;
}

function withoutTag(list: string[] | undefined, tag: string): string[] {
  return (list ?? []).filter((t) => t !== tag);
}

// Apply one op for one tag to any number of videos, in a SINGLE atomic write of
// the global file. Validates the tag id, the op and the video refs, checks the
// tag EXISTS in the vocabulary for the two ops that add a claim, and records
// provenance for every pin and suppression it writes. It throws rather than
// silently storing junk a sanitize pass would drop later: this is the one write
// path all three writers (editor UI, ops route, umtool) funnel through, and a
// mistyped id here would put a tag on records that no /tags.json can ever show.
//
// `remove` and `unsuppress` deliberately skip the vocabulary check — they only
// ever take a claim away, and an operator must be able to clean up after a tag
// whose definition has already been deleted.
//
// The read-modify-write below is atomic against other writers in THIS process
// only because this function is synchronous end to end — there is no await
// between readGlobalTags and writeGlobalTags for another handler to interleave
// in. Introducing one would silently make concurrent bulk tagging lossy.
//
// Returns which keys changed, so the caller can dirty exactly those videos.
export function applyTagAssignments(
  paths: Paths,
  input: ApplyTagAssignmentsInput,
): ApplyTagAssignmentsResult {
  const op = input.op;
  if (!OPS.includes(op)) {
    throw new Error(`unknown tag op ${JSON.stringify(op)}; expected one of ${OPS.join(", ")}`);
  }
  const tag = typeof input.tag === "string" ? input.tag.trim().toLowerCase() : "";
  if (!TAG_ID_RE.test(tag)) {
    throw new Error(
      `invalid tag id ${JSON.stringify(input.tag)}; must match ${TAG_ID_RE}`,
    );
  }
  if (!Array.isArray(input.videos)) {
    throw new Error("videos must be an array");
  }
  const keys = dedupeRefs(input.videos);
  const source = (input.source ?? "operator").trim() || "operator";
  const at = input.at ?? new Date().toISOString();

  const config = readGlobalTags(paths);
  if (
    (op === "add" || op === "suppress") &&
    !config.tags.some((def) => def.id === tag)
  ) {
    throw new Error(
      `unknown tag "${tag}" — define it first (pnpm ops tags / the /tags page)`,
    );
  }
  const changed: string[] = [];

  for (const key of keys) {
    const before = config.assignments[key];
    const manual = withoutTag(before?.manual, tag);
    const suppressed = withoutTag(before?.suppressed, tag);
    const sources: Record<string, { source: string; setAt: string }> = {
      ...(before?.sources ?? {}),
    };
    const wasManual = (before?.manual ?? []).includes(tag);
    const wasSuppressed = (before?.suppressed ?? []).includes(tag);

    let nowManual = wasManual;
    let nowSuppressed = wasSuppressed;
    switch (op) {
      case "add":
        nowManual = true;
        nowSuppressed = false; // a pin clears a rejection of the same tag
        break;
      case "remove":
        // Unpin only. A rule that matches this video still tags it — use
        // `suppress` to reject a rule-derived tag.
        nowManual = false;
        break;
      case "suppress":
        nowManual = false;
        nowSuppressed = true;
        break;
      case "unsuppress":
        nowSuppressed = false;
        break;
    }

    if (nowManual === wasManual && nowSuppressed === wasSuppressed) {
      continue; // nothing to write for this video
    }

    if (nowManual) manual.push(tag);
    if (nowSuppressed) suppressed.push(tag);
    if (nowManual || nowSuppressed) {
      // Provenance is re-stamped whenever the claim changes: the recorded
      // source is the one that put the tag in its CURRENT state.
      sources[tag] = { source, setAt: at };
    } else {
      delete sources[tag];
    }
    // Provenance for tags this video no longer carries is dead weight.
    for (const id of Object.keys(sources)) {
      if (!manual.includes(id) && !suppressed.includes(id)) delete sources[id];
    }

    const next: CuratedTagAssignment = {
      ...(manual.length > 0 ? { manual } : {}),
      ...(suppressed.length > 0 ? { suppressed } : {}),
      ...(Object.keys(sources).length > 0 ? { sources } : {}),
    };
    if (manual.length === 0 && suppressed.length === 0) {
      // The last claim about this video is gone; drop the key entirely rather
      // than leaving an empty husk in the file.
      delete config.assignments[key];
    } else {
      config.assignments[key] = next;
    }
    changed.push(key);
  }

  if (changed.length > 0) writeGlobalTags(paths, config);
  return { op, tag, changed, touched: keys };
}

// Every assignment for one video, or undefined when it carries none.
export function assignmentFor(
  config: CuratedTagsConfig,
  channelSlug: string,
  id: string,
): CuratedTagAssignment | undefined {
  return config.assignments[assignmentKey(channelSlug, id)];
}