/**
 * Connection binding for artifacts — dependency injection instead of a pinned
 * account.
 *
 * A codemode address is five segments:
 * `tools.<integration>.<org|user>.<connection>.<tool>`. That is the right shape
 * for `execute`, where the model is discovering what exists and has to say
 * exactly which row it means. It is the wrong shape for a SAVED artifact: the
 * middle two segments are the author's own connection identity, and freezing
 * them into stored source means the artifact can only ever run as its author.
 * Share it and every `.user.` path resolves against the viewer's subject
 * instead, so the row is invisible and the call fails per-query.
 *
 * So artifact code names an integration ROLE, never a connection:
 *
 *     tools.vercel.domains.getDomains            // the sole vercel role
 *     tools.linear("prod").issues.list           // one of several linear roles
 *     tools.linear("staging").issues.list
 *
 * and the connection arrives at invoke time. `create-artifact` extracts the
 * roles the code actually uses, resolves each to one of the AUTHOR's
 * connections, and persists the result on the artifact row; `execute-action`
 * turns role + stored binding back into the five-segment address immediately
 * before executing. The model-facing address loses two segments and gains
 * portability: rebinding a shared artifact later is a row update, not a rewrite.
 *
 * This is the same model the custom-tools (apps) plugin already uses
 * (`resolveIntegrationBindings` in `@executor-js/plugin-apps`): a tool declares
 * integrations as fields, the caller supplies connections, and the error names
 * the candidates when it can't choose. The vocabulary is deliberately shared —
 * "role", "binding", "choose one of ...".
 *
 * Everything above `resolveArtifactBindings` is pure and string-only, so the
 * grammar can be tested without a store, an executor or a server.
 */

import {
  ConnectionName,
  IntegrationSlug,
  type ArtifactBinding,
  type ArtifactBindings,
  type Owner,
} from "@executor-js/sdk";

// ---------------------------------------------------------------------------
// Vocabulary
// ---------------------------------------------------------------------------

/** One integration slot an artifact's code depends on. The `role` is the key
 *  bindings are stored under: a model-chosen label for the explicit form, or
 *  the integration slug itself for the implicit single-account form. */
export interface ArtifactRole {
  readonly role: string;
  readonly integration: string;
}

/** What a caller's connection looks like to this module — the projection of
 *  `Connection` that binding needs. Structural, so `executor.connections.list`
 *  satisfies it directly. */
export interface BindableConnection {
  readonly integration: string;
  readonly owner: Owner;
  readonly name: string;
}

/**
 * Roots under `tools` that are not integrations and therefore never bind.
 *
 * `tools.search(...)`, `tools.describe.tool(...)` and
 * `tools.executor.coreTools.*` are executor's own system tools; they resolve
 * without a connection and are the same for every viewer, so they pass through
 * both extraction and resolution untouched.
 */
export const RESERVED_TOOL_ROOTS: ReadonlySet<string> = new Set(["search", "describe", "executor"]);

// ---------------------------------------------------------------------------
// Extraction
// ---------------------------------------------------------------------------

/**
 * Blanks line and block comments, preserving length and newlines.
 *
 * Only comments — NOT string literals. The role in `tools.linear("prod")` *is*
 * a string literal, so blanking those would erase the very thing being read.
 * Commented-out code is the realistic false-positive source (a model leaving
 * `// tools.github.issues.list` behind would otherwise acquire a github role it
 * never calls); a `tools.` path inside a live string literal is not something
 * generators write, and binding one extra role is a visible, explainable error
 * rather than a silent wrong answer.
 */
const withCommentsBlanked = (code: string): string =>
  code.replace(/\/\/[^\n]*|\/\*[\s\S]*?\*\//g, (text) => text.replace(/[^\n]/g, " "));

/**
 * A `tools.<root>` reference, with the optional role call that follows it.
 *
 * The role is captured from either quote flavour. Anything else after the root
 * — property access, a call with an object — is left to the caller's own path
 * handling; extraction only cares which integration slot is being reached.
 */
const TOOLS_REFERENCE =
  /(?<![.\w$])tools\s*\.\s*([A-Za-z_$][\w$]*)\s*(?:\(\s*(?:"((?:[^"\\]|\\.)*)"|'((?:[^'\\]|\\.)*)')\s*\))?/g;

/**
 * An old-style address: a tier literal in the segment right after the
 * integration, i.e. `tools.<integration>.user.` / `tools.<integration>.org.`.
 *
 * Scoped to exactly those two literals in exactly that position. A tool whose
 * own first path segment is literally `user` or `org` would be caught by this
 * (`tools.acme.user.profile.get`), which is the accepted false-positive
 * surface: the two words are reserved by the address grammar itself, the shape
 * is vanishingly rare, and the error says precisely what to write instead.
 */
const OLD_STYLE_TIER_SEGMENT = /(?<![.\w$])tools\s*\.\s*([A-Za-z_$][\w$]*)\s*\.\s*(user|org)\s*\./;

/** The message a five-segment path in artifact code is refused with. */
export const oldStyleAddressRejection = (code: string): string | null => {
  const match = OLD_STYLE_TIER_SEGMENT.exec(withCommentsBlanked(code));
  if (!match) return null;
  const [, integration = "", tier = ""] = match;
  return [
    `Artifact code must not name a connection: \`tools.${integration}.${tier}.…\` pins this artifact to one account.`,
    `Address the integration only — \`tools.${integration}.<tool>(args)\` — and the server binds it to your connection when the artifact runs.`,
    `Discovery through \`execute\` still uses the full \`tools.${integration}.${tier}.<connection>.<tool>\` address; only saved artifact code drops the middle segments.`,
    `If this artifact needs two accounts of the same integration, tag each one with a role — \`tools.${integration}("prod").<tool>(args)\` — and pass \`connections: { "prod": "${integration}.${tier}.<connection>" }\` to create-artifact.`,
  ].join(" ");
};

/**
 * The integration roles an artifact's code depends on, in first-use order.
 *
 * `tools.vercel.…` contributes the implicit role `"vercel"` — the single
 * account case, where the integration slug names its own sole slot.
 * `tools.linear("prod").…` contributes the explicit role `"prod"`. Reserved
 * system roots contribute nothing. Repeat references collapse.
 */
export const extractArtifactRoles = (code: string): readonly ArtifactRole[] => {
  const scannable = withCommentsBlanked(code);
  const found = new Map<string, ArtifactRole>();
  for (const match of scannable.matchAll(TOOLS_REFERENCE)) {
    const integration = match[1];
    if (integration === undefined || RESERVED_TOOL_ROOTS.has(integration)) continue;
    const role = match[2] ?? match[3] ?? integration;
    if (role.length === 0) continue;
    if (!found.has(role)) found.set(role, { role, integration });
  }
  return [...found.values()];
};

// ---------------------------------------------------------------------------
// Resolution at create time
// ---------------------------------------------------------------------------

/** `tools.linear.org.linearProd` or the bare `linear.org.linearProd` — both are
 *  accepted, because `connections.list` reports the prefixed form and the
 *  create-artifact contract documents the bare one. */
const parseConnectionAddress = (address: string): ArtifactBinding | null => {
  const trimmed = address.trim();
  const body = trimmed.startsWith("tools.") ? trimmed.slice("tools.".length) : trimmed;
  const [integration, owner, connection, ...rest] = body.split(".");
  if (rest.length > 0) return null;
  if (integration === undefined || integration.length === 0) return null;
  if (owner !== "user" && owner !== "org") return null;
  if (connection === undefined || connection.length === 0) return null;
  return {
    integration: IntegrationSlug.make(integration),
    owner,
    connection: ConnectionName.make(connection),
  };
};

const bindingAddress = (binding: ArtifactBinding): string =>
  `${binding.integration}.${binding.owner}.${binding.connection}`;

/** The `<integration>.<tier>.<connection>` triple, which is what `connections`
 *  takes and what every candidate list prints. */
const connectionAddress = (connection: BindableConnection | undefined): string =>
  connection === undefined
    ? ""
    : `${connection.integration}.${connection.owner}.${connection.name}`;

const candidateList = (connections: readonly BindableConnection[]): string =>
  connections.map(connectionAddress).join(", ");

/** Resolution either produces the bindings to persist, or a message for the
 *  model explaining what to pass. Never a defect: every failure here is
 *  something the model can act on. */
export type BindingResolution =
  | { readonly ok: true; readonly bindings: ArtifactBindings }
  | { readonly ok: false; readonly message: string };

/**
 * Bind every role the code uses to one of the author's connections.
 *
 * - A role named in `connections` takes that connection, once it is confirmed
 *   to exist and to belong to the role's integration.
 * - A role left out is inferred: exactly one connection for that integration
 *   binds silently (the overwhelmingly common single-account case), none or
 *   several is an error naming the candidates.
 * - A `connections` key that matches no role in the code is an error, because
 *   it means the model believes it wrote something it didn't.
 *
 * `available` is the author's full connection inventory across both tiers —
 * the scoped executor has already narrowed it to what this caller may see, so
 * inference can never bind a connection the author couldn't call themselves.
 */
export const resolveArtifactBindings = (input: {
  readonly roles: readonly ArtifactRole[];
  readonly connections?: Readonly<Record<string, string>> | undefined;
  readonly available: readonly BindableConnection[];
}): BindingResolution => {
  const supplied = input.connections ?? {};
  const byRole = new Map(input.roles.map((role) => [role.role, role]));

  // Two roles of different integrations cannot share a name: `bindings` is
  // keyed by role alone, so the collision would silently drop one of them.
  const integrationByRole = new Map<string, string>();
  for (const role of input.roles) {
    const seen = integrationByRole.get(role.role);
    if (seen !== undefined && seen !== role.integration) {
      return {
        ok: false,
        message: [
          `The role "${role.role}" is used for two different integrations (${seen} and ${role.integration}).`,
          "Each role names one connection, so give them distinct names —",
          `for example \`tools.${seen}("${seen}${role.role}")\` and \`tools.${role.integration}("${role.integration}${role.role}")\`.`,
        ].join(" "),
      };
    }
    integrationByRole.set(role.role, role.integration);
  }

  for (const role of Object.keys(supplied)) {
    if (byRole.has(role)) continue;
    const known = [...byRole.keys()];
    return {
      ok: false,
      message: [
        `connections names the role "${role}", but the code never uses it.`,
        known.length > 0
          ? `The roles this artifact uses are ${known.map((name) => `"${name}"`).join(", ")}.`
          : "The code makes no integration calls at all.",
        'A role is either the integration slug (`tools.linear.…` -> "linear") or the string passed to it (`tools.linear("prod").…` -> "prod").',
      ].join(" "),
    };
  }

  const bindings: Record<string, ArtifactBinding> = {};
  for (const { role, integration } of input.roles) {
    const requested = supplied[role];
    if (requested !== undefined) {
      const parsed = parseConnectionAddress(requested);
      if (!parsed) {
        return {
          ok: false,
          message: [
            `connections["${role}"] is not a connection address: "${requested}".`,
            "Use the `<integration>.<user|org>.<connection>` triple from `tools.executor.coreTools.connections.list({})`,",
            'for example "linear.org.linearProd".',
          ].join(" "),
        };
      }
      const match = input.available.find(
        (connection) =>
          connection.integration === parsed.integration &&
          connection.owner === parsed.owner &&
          connection.name === parsed.connection,
      );
      if (!match) {
        const candidates = input.available.filter(
          (connection) => connection.integration === integration,
        );
        return {
          ok: false,
          message: [
            `No connection "${bindingAddress(parsed)}" for role "${role}".`,
            candidates.length > 0
              ? `Choose one of ${candidateList(candidates)}.`
              : `You have no ${integration} connection; connect one first.`,
          ].join(" "),
        };
      }
      if (match.integration !== integration) {
        return {
          ok: false,
          message: [
            `Role "${role}" is used as \`tools.${integration}(…)\`, but connections["${role}"] is a ${match.integration} connection.`,
            "A role's connection must belong to the integration the code calls it on.",
          ].join(" "),
        };
      }
      bindings[role] = {
        integration: IntegrationSlug.make(integration),
        owner: match.owner,
        connection: ConnectionName.make(match.name),
      };
      continue;
    }

    const candidates = input.available.filter(
      (connection) => connection.integration === integration,
    );
    const only = candidates.length === 1 ? candidates[0] : undefined;
    if (only) {
      bindings[role] = {
        integration: IntegrationSlug.make(integration),
        owner: only.owner,
        connection: ConnectionName.make(only.name),
      };
      continue;
    }
    if (candidates.length === 0) {
      return {
        ok: false,
        message: [
          `No ${integration} connection to bind role "${role}" to.`,
          `Connect ${integration} first, then create the artifact again.`,
        ].join(" "),
      };
    }
    const [first] = candidates;
    return {
      ok: false,
      message: [
        `Role "${role}" is ambiguous: you have ${candidates.length} ${integration} connections — ${candidateList(candidates)}.`,
        `Pass connections to create-artifact to choose, e.g. connections: { "${role}": "${connectionAddress(first)}" }.`,
        "To use several of them in one artifact, tag each call site with its own role —",
        `\`tools.${integration}("prod")\` / \`tools.${integration}("staging")\` — and name every role in connections.`,
      ].join(" "),
    };
  }

  return { ok: true, bindings };
};

// ---------------------------------------------------------------------------
// Resolution at execute time
// ---------------------------------------------------------------------------

/** A five-segment address, i.e. one that already carries its own tier and
 *  connection. Used only by the grandfather path below. */
const isFullAddressPath = (path: readonly string[]): boolean =>
  path.length >= 4 && (path[1] === "user" || path[1] === "org");

export type CallAddressResolution =
  | { readonly ok: true; readonly path: readonly string[] }
  | {
      readonly ok: false;
      readonly error: "binding_unresolved";
      readonly role: string;
      readonly integration: string;
      readonly message: string;
    };

/**
 * Turn one artifact-shaped call into the address the executor runs.
 *
 * `["vercel","domains","getDomains"]` with role `undefined` and a binding for
 * `"vercel"` becomes `["vercel","user","personalVercel","domains","getDomains"]`.
 * `["linear","issues","list"]` with role `"prod"` looks the binding up under
 * `"prod"` instead.
 *
 * Two paths deliberately bypass binding:
 *
 *  - **System tools.** `tools.search`, `tools.describe.*` and
 *    `tools.executor.*` name no integration and need no connection.
 *  - **Grandfathering.** Artifacts written before this contract stored
 *    five-segment paths and have `bindings: null`. Rather than migrate dev-only
 *    rows or leave them broken, a call whose path is already a well-formed
 *    address, from an artifact that has no bindings at all, executes as written.
 *    The condition is deliberately narrow: any artifact WITH bindings resolves
 *    through them, so a new artifact can never smuggle a literal connection
 *    through this door.
 */
export const resolveCallAddress = (input: {
  readonly path: readonly string[];
  readonly role?: string | undefined;
  readonly bindings: ArtifactBindings | null;
}): CallAddressResolution => {
  const [root, ...rest] = input.path;
  if (root === undefined) {
    return {
      ok: false,
      error: "binding_unresolved",
      role: "",
      integration: "",
      message: "This artifact made a tool call with no path.",
    };
  }

  if (input.role === undefined && RESERVED_TOOL_ROOTS.has(root)) {
    return { ok: true, path: input.path };
  }

  const role = input.role ?? root;
  const binding = input.bindings?.[role];
  if (binding) {
    return { ok: true, path: [binding.integration, binding.owner, binding.connection, ...rest] };
  }

  if (input.role === undefined && input.bindings === null && isFullAddressPath(input.path)) {
    return { ok: true, path: input.path };
  }

  const known = Object.keys(input.bindings ?? {});
  return {
    ok: false,
    error: "binding_unresolved",
    role,
    integration: root,
    message: [
      `This artifact has no connection bound for the role "${role}" (${root}).`,
      known.length > 0
        ? `It is bound for ${known.map((name) => `"${name}"`).join(", ")}.`
        : "It has no connection bindings at all.",
      "The connection may have been renamed or deleted since the artifact was saved — recreate it, or reconnect the integration.",
    ].join(" "),
  };
};