/**
 * The `create-artifact` tool's pure half: what the model is told, and what the server
 * refuses to render.
 *
 * The tool itself lives in `tool-server.ts` beside `execute` and `skills` —
 * this module holds only the description text and the code guard, so both can
 * be tested without standing up an MCP server.
 */

import { PROVIDED_GLOBAL_NAMES } from "@executor-js/execution";

import { oldStyleAddressRejection } from "./artifact-bindings";

/** The MCP-Apps resource the ui-bearing tools render into. */
export const MCP_APPS_SHELL_RESOURCE_URI = "ui://executor/shell.html";

/**
 * The web-app deep link for a saved artifact — the delivery path for clients
 * that can't render MCP Apps. One helper so every host emits the same shape;
 * hosts differ only in the origin and org slug they pass, and hosts with no
 * known origin (stdio) pass none and skip the link entirely.
 *
 * The console routes artifacts at `/{-$orgSlug}/artifacts/$artifactId`, where
 * the org segment is optional. Optional is not the same as absent: on a host
 * that scopes by org, a bare link resolves against whatever org the browser
 * happens to land on after auth, which is the wrong one as soon as a user
 * belongs to two. So every host that knows its session's org slug passes it,
 * exactly as `buildResumeApprovalUrl` does for the approval hand-off, and the
 * bare form is left to genuinely unscoped hosts.
 */
export const artifactUrlFor =
  (webBaseUrl: string, organizationSlug?: string | null) =>
  (artifactId: string): string => {
    const orgPath = organizationSlug ? `/${encodeURIComponent(organizationSlug)}` : "";
    return new URL(`${orgPath}/artifacts/${encodeURIComponent(artifactId)}`, webBaseUrl).toString();
  };

// ---------------------------------------------------------------------------
// Code guard
// ---------------------------------------------------------------------------
//
// Generated code is evaluated inside the shell with ~280 names already bound as
// function parameters (React hooks, TanStack Query, every shadcn/Recharts/Lucide
// export, `tools`). A `const Card = ...` in the model's source shadows the real
// binding and the component renders as a blank frame with a confusing runtime
// error — so we reject redeclarations before the code ever reaches the iframe,
// with a message that tells the model what to do instead.
//
// The other rejection is `run(...)`. It was once the escape hatch for multi-step
// composition and is now gone from the scope entirely: arbitrary code is opaque
// to the invalidation helpers (a hand-rolled `queryKey` defeats
// `queryFilter`-based refresh) and to artifact analysis, which reads
// `tools.<integration>...` paths out of the source. Code that calls it would
// fail at render time with a bare ReferenceError, so it is caught here where the
// message can point at the declarative replacement.
//
// The third rejection is a hook called inside a loop body. Models that never
// fetch the skill reach for pagination the imperative way — a `for` loop in the
// component body with a `useQuery` per page, each one `enabled` by the previous
// page's cursor. That is a rules-of-hooks violation (the hook count varies per
// render) and a silently capped read, and `.infiniteQueryOptions` is the thing
// they didn't know about. The error names it.
//
// This is deliberately NOT a general "is this good code" check. The donor branch
// also rejected array literals whose variable name looked data-ish
// (`const rows = [{...},{...}]`), which false-positives on legitimate display
// constants — chart configs, tab definitions, column headers. That heuristic is
// dropped; the "fetch live data with useQuery" guidance lives in the skill.

const REACT_DESTRUCTURING_DECLARATION = /\b(?:const|let|var)\s*\{[^{}]*\}\s*=\s*React\b/s;

/** A call to the removed `run` global. Not preceded by `.` or an identifier
 *  character, so `foo.run(...)` and `rerun(...)` — a component's own helpers —
 *  stay legal. */
const REMOVED_RUN_CALL = /(?<![.\w$])run\s*\(/;

const OBJECT_DESTRUCTURING_DECLARATION = /\b(?:const|let|var)\s*\{([^{}]*)\}\s*=/gs;

const PROVIDED_GLOBAL_DECLARATION =
  /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\b|\bfunction\s+([A-Za-z_$][\w$]*)\s*\(|\bclass\s+([A-Za-z_$][\w$]*)\b/g;

const firstDefined = (...values: Array<string | undefined>): string | undefined =>
  values.find((value): value is string => value !== undefined);

const localDestructuredName = (part: string): string | undefined => {
  const binding = part
    .replace(/^\s*\.\.\./, "")
    .split("=")[0]
    ?.trim();
  const alias = binding?.match(/:\s*([A-Za-z_$][\w$]*)\s*$/)?.[1];
  return alias ?? binding?.match(/^([A-Za-z_$][\w$]*)\b/)?.[1];
};

/** A component's own local `run` — legal, since it shadows nothing anymore. */
const LOCAL_RUN_DECLARATION = /\b(?:const|let|var|function)\s+run\b/;

// ---------------------------------------------------------------------------
// Hooks inside loop bodies
// ---------------------------------------------------------------------------
//
// Finding a loop's body needs brace matching, not a regex — a regex either stops
// at the first `}` (missing the common nested-block shape) or runs to the last
// one (flagging a `useQuery` that merely follows a closed loop). So: blank out
// comments and string/template literals so their braces and the word "useQuery"
// can't skew the scan, then walk braces from each loop header.
//
// Nothing here is a parser. Loops assembled dynamically, hooks reached through
// a helper called from a loop, and other exotica slip past — false negatives are
// fine. A false positive is not: legal code must never be refused.

/** Replaces comments and quoted/template literals with same-length blanks, so
 *  offsets stay valid and their contents can't be mistaken for code. */
const withLiteralsBlanked = (code: string): string => {
  const blank = (text: string): string => text.replace(/[^\n]/g, " ");
  return code.replace(
    // Order matters: line comment, block comment, then each quote flavour.
    /\/\/[^\n]*|\/\*[\s\S]*?\*\/|'(?:\\.|[^'\\\n])*'|"(?:\\.|[^"\\\n])*"|`(?:\\.|[^`\\])*`/g,
    blank,
  );
};

/** A React hook call: `useFoo(`, not `x.useFoo(` and not `abusefoo(`. */
const HOOK_CALL = /(?<![.\w$])(use[A-Z][\w$]*)\s*\(/;

/** The head of a loop, up to where its body starts. `do` has no header parens. */
const LOOP_HEAD = /\b(for|while|do)\b/g;

/** The body of the loop whose keyword ends at `afterKeyword`, or `null` when it
 *  can't be delimited confidently (unbalanced braces, generator-mangled source)
 *  — in which case nothing is reported rather than something guessed. */
const loopBody = (code: string, keyword: string, afterKeyword: number): string | null => {
  let index = afterKeyword;
  const skipSpace = (): void => {
    while (index < code.length && /\s/.test(code[index] ?? "")) index += 1;
  };

  // `for (...)` / `while (...)`: step over the header's parens first. A hook in
  // the header itself is not the shape we're after.
  if (keyword !== "do") {
    skipSpace();
    if (code[index] !== "(") return null;
    let depth = 0;
    for (; index < code.length; index += 1) {
      if (code[index] === "(") depth += 1;
      else if (code[index] === ")") {
        depth -= 1;
        if (depth === 0) {
          index += 1;
          break;
        }
      }
    }
    if (depth !== 0) return null;
  }

  skipSpace();

  // Only a braced body is scanned. A braceless one has no delimiter to trust —
  // its end would have to be guessed at the next semicolon, which in JSX prose
  // can run far past the statement and reach an unrelated hook. Giving up costs
  // only `for (…) useQuery(…)`, which no generator writes.
  if (code[index] !== "{") return null;

  const start = index;
  let depth = 0;
  for (; index < code.length; index += 1) {
    if (code[index] === "{") depth += 1;
    else if (code[index] === "}") {
      depth -= 1;
      if (depth === 0) return code.slice(start + 1, index);
    }
  }
  return null;
};

/** `do` is also an ordinary English word that can appear in JSX text ahead of an
 *  expression container ("nothing to do {count}"), where `for`/`while` are
 *  protected by their required header parens. Only a `do` that starts a
 *  statement is a loop. */
const startsStatement = (code: string, at: number): boolean => {
  const before = code.slice(0, at).trimEnd();
  return before === "" || /[;{}()]$/.test(before);
};

/** The first hook called inside any loop body, or `undefined`. */
const hookCalledInLoop = (code: string): string | undefined => {
  const scannable = withLiteralsBlanked(code);
  for (const match of scannable.matchAll(LOOP_HEAD)) {
    const keyword = match[1] ?? "";
    if (keyword === "do" && !startsStatement(scannable, match.index)) continue;
    const body = loopBody(scannable, keyword, match.index + match[0].length);
    const hook = body === null ? undefined : HOOK_CALL.exec(body)?.[1];
    if (hook) return hook;
  }
  return undefined;
};

/** Hooks whose in-loop use is almost always hand-rolled cursor pagination. */
const PAGINATION_HOOKS = new Set(["useQuery", "useInfiniteQuery", "useSuspenseQuery"]);

// ---------------------------------------------------------------------------
// Edits
// ---------------------------------------------------------------------------
//
// `edit-artifact`'s pure half. An edit is an exact find-and-replace against the
// stored source, so a model changing one column of a 300-line dashboard sends
// the changed lines rather than re-emitting the whole component — the tool
// call's size scales with the edit, not the artifact.
//
// The semantics are the ones every model already knows from its own file-edit
// tool: `oldText` must match verbatim (whitespace included) and exactly once,
// unless `replaceAll` opts into every occurrence. Edits apply in order, each
// against the result of the previous, and the whole batch is atomic — any
// miss rejects the call and nothing is saved. Ambiguity is refused rather than
// resolved by picking the first hit, because a wrong pick would save silently
// and the user would see the wrong line change.

export type ArtifactEdit = {
  /** Exact text to find in the current source. */
  readonly oldText: string;
  /** What to put in its place. */
  readonly newText: string;
  /** Replace every occurrence instead of requiring `oldText` to be unique. */
  readonly replaceAll?: boolean | undefined;
};

export type AppliedArtifactEdits =
  | { readonly ok: true; readonly code: string }
  | { readonly ok: false; readonly message: string };

const countOccurrences = (haystack: string, needle: string): number =>
  haystack.split(needle).length - 1;

/** The edited source, or the first edit that could not be applied. Messages
 *  name the edit by position and say what to do, because the model retries
 *  from the message alone. */
export const applyArtifactEdits = (
  code: string,
  edits: readonly ArtifactEdit[],
): AppliedArtifactEdits => {
  let current = code;
  for (const [index, edit] of edits.entries()) {
    const position = `Edit ${index + 1} of ${edits.length}`;
    if (edit.oldText === "") {
      return { ok: false, message: `${position} has an empty oldText, which matches nothing.` };
    }
    if (edit.oldText === edit.newText) {
      return {
        ok: false,
        message: `${position} is a no-op: oldText and newText are identical.`,
      };
    }
    const occurrences = countOccurrences(current, edit.oldText);
    if (occurrences === 0) {
      return {
        ok: false,
        message: [
          `${position} matched nothing: its oldText does not appear in the current source.`,
          "Copy oldText verbatim from the source, whitespace included",
          index > 0 ? "— and remember each edit sees the result of the earlier ones." : ".",
        ].join(" "),
      };
    }
    if (occurrences > 1 && edit.replaceAll !== true) {
      return {
        ok: false,
        message: [
          `${position} is ambiguous: its oldText appears ${occurrences} times in the current source.`,
          "Include enough surrounding text to make it unique, or set replaceAll: true to change every occurrence.",
        ].join(" "),
      };
    }
    // split/join for both arms: `String.replace` gives `$&` and friends in the
    // replacement special meaning, and generated JSX is full of `$`.
    current =
      edit.replaceAll === true
        ? current.split(edit.oldText).join(edit.newText)
        : current.replace(edit.oldText, () => edit.newText);
  }
  return { ok: true, code: current };
};

// ---------------------------------------------------------------------------
// Create-time smoke render
// ---------------------------------------------------------------------------

/**
 * What a server-side trial render concluded, as this package sees it.
 *
 * Declared here rather than imported so the MCP host keeps no type dependency
 * on the shell package — `@executor-js/mcp-apps-shell`'s renderer satisfies this
 * structurally, and a host that has no renderer to inject does not have to
 * resolve the module at all.
 */
export type ArtifactSmokeRenderResult =
  | {
      readonly status: "ok";
      /**
       * The markup the render produced, when it produced any within its cap.
       *
       * The smoke render is driven with a transport that never settles, so this
       * is the artifact's LOADING state — its real composition with no data in
       * it — which is what makes it storable as the gallery's layout preview.
       * Absent whenever nothing could be concluded, and every reader treats
       * absent as "fall back", never as "empty".
       */
      readonly markup?: string;
    }
  | { readonly status: "failed"; readonly message: string; readonly componentStack?: string };

/** The leading frames of a component stack: enough to locate the component that
 *  threw, not so much that the message is a wall. */
const COMPONENT_STACK_FRAMES = 6;

const trimmedComponentStack = (stack: string): string =>
  stack
    .split("\n")
    .map((line) => line.trim())
    .filter((line) => line.length > 0)
    .slice(0, COMPONENT_STACK_FRAMES)
    .join("\n");

/**
 * Turn a failed smoke render into the message the model is refused with.
 *
 * The real error, verbatim, plus where it happened and what class of problem it
 * is. The last part matters: saying the render happened with every query still
 * pending tells the model that guarding the loading state is a valid fix, which
 * is not obvious from `Cannot read properties of undefined` alone.
 */
export const smokeRenderRejection = (result: ArtifactSmokeRenderResult): string | null => {
  if (result.status === "ok") return null;
  return [
    `This component threw on its first render, so the artifact would show an error instead of a UI: ${result.message}`,
    result.componentStack ? `\n${trimmedComponentStack(result.componentStack)}\n` : "",
    "The render happened with every query still pending and no data returned — exactly the state the user sees first — so guard the loading state (`if (query.isLoading) return <ArtifactLoading />`) and read possibly-absent data with `?.`.",
    "Fix the component and call create-artifact again.",
  ]
    .filter((part) => part.length > 0)
    .join(" ");
};

// ---------------------------------------------------------------------------
// Provider pairing
// ---------------------------------------------------------------------------
//
// A handful of the components in scope read a React context that only their own
// wrapper supplies, and throw outright when it is missing. `<ChartTooltipContent
// />` outside a `<ChartContainer>` is the case this was written for: the
// artifact saves, the row is fine, and then the page dies on first render with
// `useChart must be used within a <ChartContainer />` — a failure the user sees
// and the model never does.
//
// The check is a table, not an analysis. If a name that requires a wrapper
// appears anywhere in the code and the wrapper's name appears nowhere, the code
// cannot possibly be correct, so it is refused with the pairing spelled out.
// That is deliberately weaker than the smoke render below (which catches the
// same class properly, and much more): this pass is free, runs first, and gives
// a message that names the fix rather than quoting a stack.
//
// Scope: `packages/react`'s components that `throw` on a missing context are
// `useChart` (chart.tsx), `useCarousel` (carousel.tsx), `useFormField`
// (form.tsx) and `useSidebar` (sidebar.tsx). Only the chart family is exported
// from the shell's component barrel, so only it is listed. `Tooltip` needs a
// `TooltipProvider` too, but the shell's inner renderer already wraps every
// artifact in one, so requiring it here would refuse working code.

/** Names whose presence obliges a wrapper, and the wrapper each one needs. */
const PROVIDER_PAIRINGS: readonly {
  readonly required: string;
  readonly dependents: readonly string[];
  readonly hint: string;
}[] = [
  {
    required: "ChartContainer",
    dependents: [
      "useChart",
      "ChartTooltip",
      "ChartTooltipContent",
      "ChartLegend",
      "ChartLegendContent",
    ],
    hint: 'Wrap the chart in `<ChartContainer config={{ series: { label: "Series", color: "var(--chart-1)" } }} className="h-[240px] w-full">…</ChartContainer>`.',
  },
];

/**
 * Whether `name` is INVOKED — rendered as `<Name`, or called as `name(`.
 *
 * Deliberately narrower than "the word appears". JSX text is ordinary prose
 * inside the source (`<CardContent>No ChartTooltipContent here</CardContent>`)
 * and is not blanked by `withLiteralsBlanked`, because it is not a literal — so
 * a bare-word match would refuse a component that merely names another one in
 * its copy. Requiring a `<` or a `(` costs only the alias case
 * (`const T = ChartTooltip`), which is a false negative, and false negatives are
 * the side to err on: the smoke render below catches it anyway.
 */
const invokesName = (scannable: string, name: string): boolean =>
  new RegExp(String.raw`<\s*${name}(?![\w$])|(?<![.\w$])${name}\s*\(`).test(scannable);

/** Whether `name` appears at all as an identifier. Used for the WRAPPER side,
 *  where a loose match is the safe direction: over-crediting a wrapper lets a
 *  broken artifact through to the smoke render, while under-crediting one would
 *  refuse working code. */
const mentionsName = (scannable: string, name: string): boolean =>
  new RegExp(String.raw`(?<![.\w$])${name}(?![\w$])`).test(scannable);

/** The first pairing the code breaks, or `null`. Comments and string literals
 *  are blanked first, so a name that only appears in a commented-out line
 *  neither triggers a rejection nor satisfies one. */
const providerPairingRejection = (code: string): string | null => {
  const scannable = withLiteralsBlanked(code);
  for (const pairing of PROVIDER_PAIRINGS) {
    if (mentionsName(scannable, pairing.required)) continue;
    const dependent = pairing.dependents.find((name) => invokesName(scannable, name));
    if (!dependent) continue;
    return [
      `\`${dependent}\` only works inside a \`<${pairing.required}>\`, which this code never renders.`,
      `It reads a React context that \`${pairing.required}\` provides, so it throws on the first render and the artifact shows an error instead of a UI.`,
      pairing.hint,
    ].join(" ");
  }
  return null;
};

/** `null` when the code may be rendered, otherwise the reason to hand back. */
export const validateArtifactCode = (code: string): string | null => {
  // Checked first: a five-segment address is the mistake a model that only read
  // the `execute` skill will make, and every other rejection below would be a
  // confusing thing to hear about code whose real problem is its addressing.
  const oldStyleAddress = oldStyleAddressRejection(code);
  if (oldStyleAddress) return oldStyleAddress;

  if (REMOVED_RUN_CALL.test(code) && !LOCAL_RUN_DECLARATION.test(code)) {
    return [
      "`run(code)` no longer exists — artifact code is purely declarative `tools.*`.",
      "Read data with useQuery(tools.<ns>.<tool>.queryOptions(args)),",
      "page through a cursor with useInfiniteQuery(tools.<ns>.<tool>.infiniteQueryOptions(args, { getNextPageParam })),",
      "and write with useMutation(tools.<ns>.<tool>.mutationOptions({ onSuccess })).",
    ].join(" ");
  }

  const loopedHook = hookCalledInLoop(code);
  if (loopedHook) {
    return [
      `\`${loopedHook}\` is called inside a loop body.`,
      "React hooks must run unconditionally at the top level of the component, in the same order every render.",
      PAGINATION_HOOKS.has(loopedHook)
        ? "To read every page of a cursor, use one useInfiniteQuery(tools.<ns>.<tool>.infiniteQueryOptions(args, { cursorKey, getNextPageParam })) and render data.pages — never a loop of useQuery calls, one per page."
        : "Move the hook out of the loop, and derive per-item values from its result instead.",
    ].join(" ");
  }

  const missingProvider = providerPairingRejection(code);
  if (missingProvider) return missingProvider;

  if (REACT_DESTRUCTURING_DECLARATION.test(code)) {
    return [
      "Do not destructure React in create-artifact.",
      "Hooks such as useState are already in scope; use useState(...) directly or React.useState(...).",
    ].join(" ");
  }

  for (const match of code.matchAll(OBJECT_DESTRUCTURING_DECLARATION)) {
    const names = match[1]?.split(",").flatMap((part) => {
      const name = localDestructuredName(part);
      return name ? [name] : [];
    });
    const providedName = names?.find((name) => PROVIDED_GLOBAL_NAMES.has(name));
    if (providedName) {
      return [
        `Provided global "${providedName}" is already in scope and cannot be redeclared.`,
        "Remove the destructuring declaration and use the provided global directly.",
      ].join(" ");
    }
  }

  for (const match of code.matchAll(PROVIDED_GLOBAL_DECLARATION)) {
    const name = firstDefined(match[1], match[2], match[3]);
    if (name && PROVIDED_GLOBAL_NAMES.has(name)) {
      return [
        `Provided global "${name}" is already in scope and cannot be redeclared.`,
        "Remove the local declaration and use the provided global directly.",
      ].join(" ");
    }
  }

  return null;
};