/**
 * Additive merge and surgical removal of the fragments opencodex owns.
 *
 * The rule that shapes this file: we insert exactly the paths our builder
 * named, and we delete exactly the paths a record says we wrote. Nothing here
 * ever scans for a prefix — a user's own `opencodex/...` entry is not ours to
 * remove, and inferring ownership from a name is how a config editor destroys
 * work it did not create.
 *
 * Design of record: devlog/_fin/260802_client_toggle_api/031_wp3_writer_impl.md.
 */
import type { ManagedContribution } from "../clients/config-export/contracts";

function isPlainRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

/** Structured clone via JSON: our documents are plain data by construction. */
function clone<T>(value: T): T {
  return value === undefined ? value : (JSON.parse(JSON.stringify(value)) as T);
}

/**
 * `[field=value]` addresses the ONE element of a sequence whose `field` equals
 * `value`, and `[v2:field=value,field=value]` the one whose every named field
 * matches. Raycast keeps its providers as a YAML list, so the element is the
 * smallest thing we can own there; an index would move under us the moment
 * the user reordered their own entries. Any other segment is a plain key.
 *
 * A conjunction exists because one field is not always the identity. ZCode
 * keys a model rule in its provider store by the PAIR `(providerId, modelId)`,
 * so a `[modelId=…]` selector alone would match another provider's rule for the
 * same model and then replace it, in a file holding every provider the user
 * has. Addressing an element by less than what identifies it is the same
 * defect as addressing it by index.
 *
 * The single-criterion spelling keeps its original grammar, where the value may
 * itself contain commas and equals signs. A conjunction uses an explicit v2
 * marker, so no path already written into an ownership record on disk changes
 * meaning. Once the marker is present the whole segment must be valid; falling
 * back to a key or v1 selector would recreate the silent reselection hazard.
 */
const ARRAY_SELECTOR = /^\[([A-Za-z_][A-Za-z0-9_]*)=([^\]]+)\]$/u;
const SELECTOR_FIELD = /^[A-Za-z_][A-Za-z0-9_]*$/u;
const SELECTOR_CONJUNCTION_PREFIX = "[v2:";

/** One `field=value` equality a selector requires of the element it names. */
export interface SelectorCriterion {
  field: string;
  value: string;
}

export type PathSegment =
  | { kind: "key"; key: string }
  | { kind: "select"; criteria: readonly SelectorCriterion[] };

/** A reserved v2 selector marker was present, but its complete grammar was not. */
export class InvalidSelectorError extends Error {
  constructor() {
    super("invalid versioned selector");
    this.name = "InvalidSelectorError";
  }
}

function validConjunctionCriteria(criteria: readonly SelectorCriterion[]): boolean {
  return criteria.length >= 2 && criteria.every(criterion => (
    SELECTOR_FIELD.test(criterion.field)
    && criterion.value.length > 0
    && !criterion.value.includes(",")
    && !criterion.value.includes("]")
  ));
}

/** Spell a multi-field selector without colliding with persisted v1 paths. */
export function formatSelectorConjunction(criteria: readonly SelectorCriterion[]): string | null {
  if (!validConjunctionCriteria(criteria)) return null;
  return `${SELECTOR_CONJUNCTION_PREFIX}${criteria
    .map(criterion => `${criterion.field}=${criterion.value}`)
    .join(",")}]`;
}

export function parseSegment(raw: string): PathSegment {
  if (raw.startsWith(SELECTOR_CONJUNCTION_PREFIX)) {
    if (!raw.endsWith("]")) throw new InvalidSelectorError();
    const parts = raw.slice(SELECTOR_CONJUNCTION_PREFIX.length, -1).split(",");
    const criteria = parts.map(part => {
      const equals = part.indexOf("=");
      return equals < 0
        ? { field: "", value: "" }
        : { field: part.slice(0, equals), value: part.slice(equals + 1) };
    });
    if (!validConjunctionCriteria(criteria)) throw new InvalidSelectorError();
    return {
      kind: "select",
      criteria,
    };
  }
  const match = ARRAY_SELECTOR.exec(raw);
  if (!match) return { kind: "key", key: raw };
  return { kind: "select", criteria: [{ field: match[1]!, value: match[2]! }] };
}

/** The `field=value` list a selector segment spells, for messages and seeding. */
export function selectorPairs(criteria: readonly SelectorCriterion[]): string {
  return criteria.map(criterion => `${criterion.field}=${criterion.value}`).join(", ");
}

/**
 * Thrown when a selector matches more than one element. Picking either one
 * would silently rewrite an entry the user may have written; the writer maps
 * this to an `unsafe` refusal instead.
 */
export class AmbiguousSelectorError extends Error {
  constructor(criteria: readonly SelectorCriterion[]) {
    super(`more than one entry has ${selectorPairs(criteria)}`);
    this.name = "AmbiguousSelectorError";
  }
}

/** The index of the element a selector names, -1 when none matches. */
export function selectIndex(items: readonly unknown[], criteria: readonly SelectorCriterion[]): number {
  const matches: number[] = [];
  items.forEach((item, index) => {
    if (isPlainRecord(item) && criteria.every(criterion => item[criterion.field] === criterion.value)) {
      matches.push(index);
    }
  });
  if (matches.length > 1) throw new AmbiguousSelectorError(criteria);
  return matches[0] ?? -1;
}

function assertNever(segment: never): never {
  throw new Error(`unknown path segment ${JSON.stringify(segment)}`);
}

/** The element a selector names, or `undefined` when none matches. */
function selectElement(items: readonly unknown[], segment: PathSegment & { kind: "select" }): unknown {
  return items[selectIndex(items, segment.criteria)];
}

/**
 * Read `path` through the same segment grammar `setPath` writes through.
 *
 * It belongs here rather than beside the classifier because the grammar does: a
 * reader that resolved a selector differently from the writer would report one
 * element as ours and then rewrite another. `state` re-exports it for the
 * callers that have always imported it from there.
 */
export function readPath(doc: unknown, path: readonly string[]): unknown {
  let cursor: unknown = doc;
  // Validate the complete persisted grammar before document shape can short-circuit
  // the walk. Otherwise an absent early key can hide a malformed later selector,
  // making an unreadable ownership record look absent and move the operation to a
  // different file.
  const segments = path.map(parseSegment);
  for (const segment of segments) {
    switch (segment.kind) {
      case "key":
        if (!isPlainRecord(cursor)) return undefined;
        cursor = cursor[segment.key];
        break;
      case "select":
        if (!Array.isArray(cursor)) return undefined;
        cursor = selectElement(cursor, segment);
        break;
      default:
        return assertNever(segment);
    }
    if (cursor === undefined) return undefined;
  }
  return cursor;
}

/**
 * Write `value` at `path`, creating intermediate containers. Returns a new document.
 *
 * A `key` segment descends through a record, creating `{}` where the slot is
 * absent or holds something else. A `select` segment descends through an
 * array the same way, creating `[]`; a missing element is pushed, a matching
 * one is replaced in place so the user's ordering survives.
 */
export function setPath(doc: unknown, path: readonly string[], value: unknown): unknown {
  if (path.length === 0) throw new Error("setPath needs a non-empty path");
  /*
   * `parent[slot]` is the position the segment just consumed addresses. The
   * root sits in a one-key holder so the first segment needs no special case:
   * a non-record document is replaced by `{}` exactly as before.
   */
  const holder: Record<string, unknown> = { root: isPlainRecord(doc) ? clone(doc) : {} };
  let parent: Record<string, unknown> | unknown[] = holder;
  let slot: string | number = "root";
  const read = (): unknown => (Array.isArray(parent) ? parent[slot as number] : parent[slot as string]);
  const write = (next: unknown): void => {
    if (Array.isArray(parent)) parent[slot as number] = next;
    else parent[slot as string] = next;
  };
  for (const raw of path) {
    const segment = parseSegment(raw);
    switch (segment.kind) {
      case "key": {
        if (!isPlainRecord(read())) write({});
        parent = read() as Record<string, unknown>;
        slot = segment.key;
        break;
      }
      case "select": {
        if (!Array.isArray(read())) write([]);
        const items = read() as unknown[];
        const found = selectIndex(items, segment.criteria);
        parent = items;
        if (found >= 0) {
          slot = found;
        } else {
          // Seed the element so the selector stays true for whatever a deeper
          // segment writes into it; a last-position select replaces it whole.
          slot = items.length;
          items.push(Object.fromEntries(segment.criteria.map(criterion => [criterion.field, criterion.value])));
        }
        break;
      }
      default:
        return assertNever(segment);
    }
  }
  write(clone(value));
  return holder.root;
}

/**
 * Delete `path`, optionally pruning containers that WE created.
 *
 * Two properties have to hold at once, and they pull in opposite directions.
 * A user who wrote `providers: {}` before we existed still has it after a
 * disable — pruning it because our entry left it empty would delete their
 * line. But a container we conjured ourselves (Kimi's `models` map exists only
 * because our aliases need somewhere to live) must not survive as empty
 * residue in a file the user never asked us to restructure.
 *
 * `createdContainers` is the difference: paths recorded at apply time as
 * absent beforehand. Anything not in that set is treated as the user's.
 */
export function deletePath(
  doc: unknown,
  path: readonly string[],
  createdContainers: ReadonlySet<string> = new Set(),
): { doc: unknown; removed: boolean } {
  if (!isPlainRecord(doc) || path.length === 0) return { doc, removed: false };
  const root = clone(doc) as Record<string, unknown>;
  // `chain[i]` is the container segment `i` is resolved against; `slots[i]` is
  // the key or index it resolved to, so the prune walk can delete by position.
  const chain: (Record<string, unknown> | unknown[])[] = [root];
  const slots: (string | number)[] = [];
  for (let depth = 0; depth < path.length; depth += 1) {
    const container = chain[depth]!;
    const segment = parseSegment(path[depth]!);
    switch (segment.kind) {
      case "key": {
        if (Array.isArray(container) || !(segment.key in container)) return { doc: root, removed: false };
        slots.push(segment.key);
        chain.push(container[segment.key] as Record<string, unknown> | unknown[]);
        break;
      }
      case "select": {
        if (!Array.isArray(container)) return { doc: root, removed: false };
        const found = selectIndex(container, segment.criteria);
        if (found < 0) return { doc: root, removed: false };
        slots.push(found);
        chain.push(container[found] as Record<string, unknown> | unknown[]);
        break;
      }
      default:
        return assertNever(segment);
    }
    // Only the leaf may be a scalar; walking into one means the path is absent.
    if (depth < path.length - 1) {
      const next = chain[depth + 1];
      if (!isPlainRecord(next) && !Array.isArray(next)) return { doc: root, removed: false };
    }
  }
  const remove = (container: Record<string, unknown> | unknown[], slot: string | number): void => {
    if (Array.isArray(container)) container.splice(slot as number, 1);
    else delete container[slot as string];
  };
  remove(chain[path.length - 1]!, slots[path.length - 1]!);
  /*
   * Walk back up, pruning only containers this deletion emptied AND that we
   * created. The root is never pruned.
   */
  for (let index = path.length - 1; index >= 1; index -= 1) {
    const container = chain[index]!;
    const empty = Array.isArray(container) ? container.length === 0 : Object.keys(container).length === 0;
    if (!empty) break;
    const containerPath = path.slice(0, index).join("\u0000");
    if (!createdContainers.has(containerPath)) break;
    remove(chain[index - 1]!, slots[index - 1]!);
  }
  return { doc: root, removed: true };
}

/** Insert every fragment. Everything else in the document is preserved. */
export function mergeContribution(doc: unknown, contribution: ManagedContribution): unknown {
  let next = doc;
  for (const fragment of contribution.fragments) next = setPath(next, fragment.path, fragment.value);
  return next;
}

/**
 * Remove exactly the RECORDED paths — never a prefix scan. An entry that
 * matches our naming but has no recorded path is not ours: it reads as
 * `conflict` and survives untouched.
 */
export function removeFragments(
  doc: unknown,
  paths: readonly (readonly string[])[],
  createdContainers: ReadonlySet<string> = new Set(),
): { doc: unknown; removed: boolean } {
  let next = doc;
  let removed = false;
  for (const path of paths) {
    const result = deletePath(next, path, createdContainers);
    next = result.doc;
    removed = removed || result.removed;
  }
  return { doc: next, removed };
}

/**
 * Container paths a contribution would have to CREATE in `doc`.
 *
 * Computed before the merge, because afterwards every container exists and the
 * question is unanswerable. Recorded on the ownership record so a later
 * disable can tell its own scaffolding from the user's structure.
 */
export function createdContainerPaths(
  doc: unknown,
  contribution: ManagedContribution,
): string[] {
  const created = new Set<string>();
  for (const fragment of contribution.fragments) {
    let cursor: unknown = doc;
    for (let depth = 0; depth < fragment.path.length - 1; depth += 1) {
      const segment = parseSegment(fragment.path[depth]!);
      let next: unknown;
      switch (segment.kind) {
        case "key": {
          /*
           * The container this key must hold is whatever the NEXT segment
           * descends into: an array when that is a selector, a record
           * otherwise. Either one is ours to create when absent.
           */
          const nextSegment = parseSegment(fragment.path[depth + 1]!);
          next = isPlainRecord(cursor) ? cursor[segment.key] : undefined;
          if (nextSegment.kind === "select" ? !Array.isArray(next) : !isPlainRecord(next)) next = undefined;
          break;
        }
        case "select": {
          // A selector that matches nothing means setPath will push the element.
          next = Array.isArray(cursor)
            ? cursor[selectIndex(cursor, segment.criteria)]
            : undefined;
          break;
        }
        default:
          return assertNever(segment);
      }
      if (next === undefined) {
        created.add(fragment.path.slice(0, depth + 1).join("\u0000"));
        cursor = undefined;
        continue;
      }
      cursor = next;
    }
  }
  return [...created];
}
