Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

45.2 KB
Raw Blame
import { astToFilterState } from "@/src/features/search-bar/lib/adapter";
import { filterStateToQueryText } from "@/src/features/search-bar/lib/filter-state-to-query";
import { parse } from "@/src/features/search-bar/lib/langQ";
import { validateQuery } from "@/src/features/search-bar/lib/validate";
import type { FilterState } from "@langfuse/shared";
import { createFieldRegistry, EVENTS_FIELD_REGISTRY } from "./fields";
import { planCommit } from "./commit";
import {
  applyCheckboxSelection,
  hasEmptyCheckboxSelection,
  type SidebarFilterActionContext,
} from "@/src/features/filters/lib/sidebar-filter-actions";
import {
  USERS_FIELD_REGISTRY,
  LEGACY_USERS_FIELD_REGISTRY,
} from "@/src/features/filters/config/usersSearchRegistry";

const scopedRegistry = createFieldRegistry({
  ...EVENTS_FIELD_REGISTRY,
  defaultSearchType: ["id"],
  fields: EVENTS_FIELD_REGISTRY.fields.filter(
    (field) => field.id !== "input" && field.id !== "output",
  ),
  searchScopes: {
    content: {
      searchType: ["content"],
      label: "Content",
      description: "Input and output",
    },
    all: {
      searchType: ["id", "content"],
      label: "All fields",
      description: "IDs, names, input and output",
    },
    input: {
      searchType: ["input"],
      label: "Input",
      description: "Input payload",
    },
    output: {
      searchType: ["output"],
      label: "Output",
      description: "Output payload",
    },
  },
});

describe("declared search scopes", () => {
  it("does not interpret inherited object properties as search scopes", () => {
    for (const name of ["constructor", "toString", "__proto__"]) {
      expect(scopedRegistry.resolveField(name)).toBeNull();
    }
  });
  it.each([USERS_FIELD_REGISTRY, LEGACY_USERS_FIELD_REGISTRY])(
    "does not expose scopes on fixed-lane Users registries",
    (registry) => {
      expect(registry.resolveField("in")).toBeNull();
      expect(planCommit("in:content refund", undefined, registry).status).toBe(
        "invalid",
      );
    },
  );
  it.each([
    ["refund policy", "refund policy", ["id"]],
    ['content:"refund policy" env:prod', "refund policy", ["content"]],
    ["all:refund", "refund", ["id", "content"]],
    ["input:refund", "refund", ["input"]],
    ['in:(id OR input) "refund policy"', "refund policy", ["id", "input"]],
    ['IN:(id OR input) "refund policy"', "refund policy", ["id", "input"]],
  ])("lowers %s to one backend search lane", (text, query, type) => {
    expect(planCommit(text as string, undefined, scopedRegistry)).toMatchObject(
      {
        status: "committed",
        searchQuery: query,
        searchType: type,
      },
    );
  });

  it.each([
    "content:refund output:policy",
    "content:refund refund",
    "content:(refund OR policy)",
    "-content:refund",
    "content:=refund",
    "content:refund*",
    "in:(id AND input) refund",
    "in:unsupported refund",
    "in:input content:refund",
    "in:input in:output refund",
  ])("rejects unsupported scope composition: %s", (text) => {
    const parsed = parse(text, scopedRegistry);
    const lowered = astToFilterState(parsed.ast, undefined, scopedRegistry);
    expect(lowered.errors.length).toBeGreaterThan(0);
    expect(validateQuery(text, undefined, scopedRegistry).valid).toBe(false);
    expect(planCommit(text, undefined, scopedRegistry).status).toBe("invalid");
  });

  it("reports only the phrase conflict when a scoped phrase has a compatibility scope", () => {
    const { ast } = parse("content:refund in:id", scopedRegistry);
    expect(astToFilterState(ast, undefined, scopedRegistry).errors).toEqual([
      "Only one search phrase is supported — use either bare text or one scoped search",
    ]);
    const { ast: missingPhrase } = parse("in:id", scopedRegistry);
    expect(
      astToFilterState(missingPhrase, undefined, scopedRegistry).errors,
    ).toEqual(["Add search text after in:"]);
  });

  it.each([
    ["id"],
    ["content"],
    ["input"],
    ["output"],
    ["id", "content"],
    ["id", "input"],
    ["id", "output"],
    ["input", "output"],
  ] as const)("round-trips the existing search scope %j", (...searchType) => {
    const text = filterStateToQueryText(
      [],
      {
        searchQuery: "refund policy",
        searchType: [...searchType],
      },
      scopedRegistry,
    ).text;
    expect(planCommit(text, undefined, scopedRegistry)).toMatchObject({
      status: "committed",
      searchQuery: "refund policy",
      searchType,
    });
  });

  it("keeps Events input/output as independent column filters", () => {
    expect(planCommit("input:refund output:policy")).toMatchObject({
      status: "committed",
      searchQuery: null,
      filters: [
        { column: "input", operator: "contains", value: "refund" },
        { column: "output", operator: "contains", value: "policy" },
      ],
    });
  });

  it.each(['content:""', 'content:" "'])(
    "rejects an empty scoped phrase: %s",
    (text) => {
      expect(validateQuery(text, undefined, scopedRegistry).valid).toBe(false);
      expect(planCommit(text, undefined, scopedRegistry).status).toBe(
        "invalid",
      );
    },
  );

  it("preserves spaces inside an explicit scoped phrase on projection", () => {
    const committed = planCommit(
      'content:" refund policy "',
      undefined,
      scopedRegistry,
    );
    expect(committed.status).toBe("committed");
    if (committed.status !== "committed") return;
    const projected = filterStateToQueryText(
      [],
      committed,
      scopedRegistry,
    ).text;
    expect(planCommit(projected, undefined, scopedRegistry)).toMatchObject({
      searchQuery: " refund policy ",
      searchType: ["content"],
    });
  });
});

function lower(text: string) {
  return astToFilterState(parse(text).ast);
}

describe("astToFilterState", () => {
  it("lowers a flat AND chain of facets plus free text", () => {
    const r = lower("timeout level:ERROR env:prod");
    expect(r.errors).toEqual([]);
    expect(r.searchQuery).toBe("timeout");
    expect(r.filters).toEqual([
      {
        type: "stringOptions",
        column: "level",
        operator: "any of",
        value: ["ERROR"],
      },
      {
        type: "stringOptions",
        column: "environment",
        operator: "any of",
        value: ["prod"],
      },
    ]);
  });

  it("lowers grouped values to any-of and negation to none-of", () => {
    expect(lower("level:(ERROR OR WARNING)").filters).toEqual([
      {
        type: "stringOptions",
        column: "level",
        operator: "any of",
        value: ["ERROR", "WARNING"],
      },
    ]);
    expect(lower("-env:(dev OR staging)").filters).toEqual([
      {
        type: "stringOptions",
        column: "environment",
        operator: "none of",
        value: ["dev", "staging"],
      },
    ]);
  });

  it("collapses top-level same-field OR chains into one any-of filter", () => {
    const r = lower("level:ERROR OR level:WARNING");
    expect(r.errors).toEqual([]);
    expect(r.filters).toEqual([
      {
        type: "stringOptions",
        column: "level",
        operator: "any of",
        value: ["ERROR", "WARNING"],
      },
    ]);
  });

  it("rejects cross-field OR", () => {
    const r = lower("level:ERROR OR env:dev");
    expect(r.errors.length).toBeGreaterThan(0);
    expect(r.filters).toEqual([]);
  });

  it("lowers comparisons and inverts them under negation", () => {
    expect(lower("latency:>2").filters).toEqual([
      { type: "number", column: "latency", operator: ">", value: 2 },
    ]);
    expect(lower("NOT latency:>2").filters).toEqual([
      { type: "number", column: "latency", operator: "<=", value: 2 },
    ]);
  });

  it("rejects negated numeric equality (would need an OR group)", () => {
    const r = lower("-latency:2");
    expect(r.errors.length).toBeGreaterThan(0);
  });

  it("lowers textSearch equality to contains; := to exact", () => {
    expect(lower("statusMessage:rate").filters).toEqual([
      {
        type: "string",
        column: "statusMessage",
        operator: "contains",
        value: "rate",
      },
    ]);
    expect(lower("statusMessage:=rate").filters).toEqual([
      { type: "string", column: "statusMessage", operator: "=", value: "rate" },
    ]);
    expect(lower("-statusMessage:*rate*").filters).toEqual([
      {
        type: "string",
        column: "statusMessage",
        operator: "does not contain",
        value: "rate",
      },
    ]);
  });

  it("lowers positional `*` globs to string match operators", () => {
    expect(lower("input:How*").filters).toEqual([
      {
        type: "string",
        column: "input",
        operator: "starts with",
        value: "How",
      },
    ]);
    expect(lower("output:*done").filters).toEqual([
      {
        type: "string",
        column: "output",
        operator: "ends with",
        value: "done",
      },
    ]);
    expect(lower('input:*"refund policy"*').filters).toEqual([
      {
        type: "string",
        column: "input",
        operator: "contains",
        value: "refund policy",
      },
    ]);
  });

  it("lowers array fields with any-of, none-of, and all-of", () => {
    expect(lower("tags:(a OR b)").filters).toEqual([
      {
        type: "arrayOptions",
        column: "traceTags",
        operator: "any of",
        value: ["a", "b"],
      },
    ]);
    expect(lower("-tags:a").filters).toEqual([
      {
        type: "arrayOptions",
        column: "traceTags",
        operator: "none of",
        value: ["a"],
      },
    ]);
    expect(lower("tags:(a AND b)").filters).toEqual([
      {
        type: "arrayOptions",
        column: "traceTags",
        operator: "all of",
        value: ["a", "b"],
      },
    ]);
  });

  it("lowers datetime comparisons to Date values", () => {
    const r = lower("startTime:>2026-06-01");
    expect(r.errors).toEqual([]);
    expect(r.filters).toHaveLength(1);
    const f = r.filters[0]!;
    expect(f.type).toBe("datetime");
    expect(f.operator).toBe(">");
    expect((f as { value: Date }).value instanceof Date).toBe(true);
  });

  it("lowers booleans and inverts the value under negation", () => {
    expect(lower("isRootObservation:true").filters).toEqual([
      {
        type: "boolean",
        column: "isRootObservation",
        operator: "=",
        value: true,
      },
    ]);
    expect(lower("-isRootObservation:true").filters).toEqual([
      {
        type: "boolean",
        column: "isRootObservation",
        operator: "=",
        value: false,
      },
    ]);
  });

  it("lowers metadata paths to stringObject filters", () => {
    expect(lower("metadata.region:eu").filters).toEqual([
      {
        type: "stringObject",
        column: "metadata",
        key: "region",
        operator: "=",
        value: "eu",
      },
    ]);
    expect(lower("-metadata.region:*eu*").filters).toEqual([
      {
        type: "stringObject",
        column: "metadata",
        key: "region",
        operator: "does not contain",
        value: "eu",
      },
    ]);
    expect(lower("metadata.region:>5").errors.length).toBeGreaterThan(0);
    expect(lower("-metadata.region:eu").errors.length).toBeGreaterThan(0);
  });

  it("lowers score paths to numeric or categorical columns", () => {
    expect(lower("scores.accuracy:>0.8").filters).toEqual([
      {
        type: "numberObject",
        column: "scores_avg",
        key: "accuracy",
        operator: ">",
        value: 0.8,
      },
    ]);
    expect(lower("scores.accuracy:0.5").filters).toEqual([
      {
        type: "numberObject",
        column: "scores_avg",
        key: "accuracy",
        operator: "=",
        value: 0.5,
      },
    ]);
    expect(lower("scores.feedback:positive").filters).toEqual([
      {
        type: "categoryOptions",
        column: "score_categories",
        key: "feedback",
        operator: "any of",
        value: ["positive"],
      },
    ]);
    expect(lower("-traceScores.feedback:(bad OR worse)").filters).toEqual([
      {
        type: "categoryOptions",
        column: "trace_score_categories",
        key: "feedback",
        operator: "none of",
        value: ["bad", "worse"],
      },
    ]);
  });

  it("routes numeric-looking values by observed score TYPE, not value syntax", () => {
    // `rating` is a categorical score whose labels happen to be numeric (1-5).
    // Without the score-type map the value-syntax heuristic wrongly picks the
    // numeric column; with it, the categorical column is targeted.
    const scoreTypes = {
      numericScoreNames: new Set<string>(["accuracy"]),
      categoricalScoreNames: new Set<string>(["rating"]),
      traceNumericScoreNames: new Set<string>(),
      traceCategoricalScoreNames: new Set<string>(["nps"]),
    };
    const lowerWith = (text: string) =>
      astToFilterState(parse(text).ast, scoreTypes);

    expect(lowerWith("scores.rating:5").filters).toEqual([
      {
        type: "categoryOptions",
        column: "score_categories",
        key: "rating",
        operator: "any of",
        value: ["5"],
      },
    ]);
    // A known-numeric score still lowers numeric.
    expect(lowerWith("scores.accuracy:0.5").filters).toEqual([
      {
        type: "numberObject",
        column: "scores_avg",
        key: "accuracy",
        operator: "=",
        value: 0.5,
      },
    ]);
    // Trace-level categorical with a numeric label.
    expect(lowerWith("traceScores.nps:9").filters).toEqual([
      {
        type: "categoryOptions",
        column: "trace_score_categories",
        key: "nps",
        operator: "any of",
        value: ["9"],
      },
    ]);
    // Unknown score (not observed) falls back to the value-syntax heuristic.
    expect(lowerWith("scores.unseen:5").filters).toEqual([
      {
        type: "numberObject",
        column: "scores_avg",
        key: "unseen",
        operator: "=",
        value: 5,
      },
    ]);
  });

  it("routes known boolean scores to booleanObject filters", () => {
    const scoreTypes = {
      numericScoreNames: new Set<string>(),
      categoricalScoreNames: new Set<string>(),
      booleanScoreNames: new Set<string>(["flag"]),
      traceNumericScoreNames: new Set<string>(),
      traceCategoricalScoreNames: new Set<string>(),
      traceBooleanScoreNames: new Set<string>(["traceFlag"]),
    };
    const lowerWith = (text: string) =>
      astToFilterState(parse(text).ast, scoreTypes);

    expect(lowerWith("scores.flag:true").filters).toEqual([
      {
        type: "booleanObject",
        column: "score_booleans",
        key: "flag",
        operator: "=",
        value: true,
      },
    ]);
    expect(lowerWith("-traceScores.traceFlag:false").filters).toEqual([
      {
        type: "booleanObject",
        column: "trace_score_booleans",
        key: "traceFlag",
        operator: "<>",
        value: false,
      },
    ]);
    // Comparisons fall back to the legacy numeric column — see the
    // "keeps legacy numeric filters" test below.
    expect(lowerWith("scores.flag:>0").errors).toEqual([]);
    expect(
      lowerWith("scores.flag:(true OR false)").errors.length,
    ).toBeGreaterThan(0);
  });

  it("routes boolean literals to booleanObject when legacy numeric options also include the score", () => {
    const scoreTypes = {
      numericScoreNames: new Set<string>(["flag"]),
      categoricalScoreNames: new Set<string>(),
      booleanScoreNames: new Set<string>(["flag"]),
      traceNumericScoreNames: new Set<string>(["traceFlag"]),
      traceCategoricalScoreNames: new Set<string>(),
      traceBooleanScoreNames: new Set<string>(["traceFlag"]),
    };

    expect(
      astToFilterState(parse("scores.flag:true").ast, scoreTypes).filters,
    ).toEqual([
      {
        type: "booleanObject",
        column: "score_booleans",
        key: "flag",
        operator: "=",
        value: true,
      },
    ]);
    expect(
      astToFilterState(parse("-traceScores.traceFlag:false").ast, scoreTypes)
        .filters,
    ).toEqual([
      {
        type: "booleanObject",
        column: "trace_score_booleans",
        key: "traceFlag",
        operator: "<>",
        value: false,
      },
    ]);
    expect(
      astToFilterState(parse("scores.flag:1").ast, scoreTypes).filters,
    ).toEqual([
      {
        type: "numberObject",
        column: "scores_avg",
        key: "flag",
        operator: "=",
        value: 1,
      },
    ]);
  });

  it("keeps legacy numeric filters working on boolean-observed scores", () => {
    // Boolean scores also aggregate numerically (0/1) into scores_avg. The
    // sidebar's numeric facet and pre-boolean-filter URLs/saved views still
    // produce numberObject filters on them; those must keep lowering
    // numerically — rejecting them would lock the bar red on state a
    // first-party surface created.
    const scoreTypes = {
      numericScoreNames: new Set<string>(),
      categoricalScoreNames: new Set<string>(),
      booleanScoreNames: new Set<string>(["flag"]),
      traceNumericScoreNames: new Set<string>(),
      traceCategoricalScoreNames: new Set<string>(),
      traceBooleanScoreNames: new Set<string>(["traceFlag"]),
    };
    const lowerWith = (text: string) =>
      astToFilterState(parse(text).ast, scoreTypes);

    const comparison = lowerWith("scores.flag:>=0.5");
    expect(comparison.errors).toEqual([]);
    expect(comparison.filters).toEqual([
      {
        type: "numberObject",
        column: "scores_avg",
        key: "flag",
        operator: ">=",
        value: 0.5,
      },
    ]);
    expect(lowerWith("scores.flag:1").filters).toEqual([
      {
        type: "numberObject",
        column: "scores_avg",
        key: "flag",
        operator: "=",
        value: 1,
      },
    ]);
    expect(lowerWith("traceScores.traceFlag:<1").filters).toEqual([
      {
        type: "numberObject",
        column: "trace_scores_avg",
        key: "traceFlag",
        operator: "<",
        value: 1,
      },
    ]);
    // Boolean literals still prefer the boolean column…
    expect(lowerWith("scores.flag:true").filters).toEqual([
      {
        type: "booleanObject",
        column: "score_booleans",
        key: "flag",
        operator: "=",
        value: true,
      },
    ]);
    // …and anything neither numeric nor boolean keeps the boolean diagnostic.
    expect(lowerWith("scores.flag:positive").errors.length).toBeGreaterThan(0);
  });

  it("treats := (exact) on a categorical score as a category match", () => {
    // `:=positive` must behave like the bare `:positive` (any-of category),
    // not be rejected as a comparison.
    const scoreTypes = {
      numericScoreNames: new Set<string>(),
      categoricalScoreNames: new Set<string>(["feedback"]),
      traceNumericScoreNames: new Set<string>(),
      traceCategoricalScoreNames: new Set<string>(),
    };
    const r = astToFilterState(
      parse("scores.feedback:=positive").ast,
      scoreTypes,
    );
    expect(r.errors).toEqual([]);
    expect(r.filters).toEqual([
      {
        type: "categoryOptions",
        column: "score_categories",
        key: "feedback",
        operator: "any of",
        value: ["positive"],
      },
    ]);
  });

  it("rejects a comparison operator on a categorical score", () => {
    // `feedback` is categorical → `scores.feedback:>0.8` would otherwise route
    // to the numeric column (no data) and return an empty table with no error.
    const scoreTypes = {
      numericScoreNames: new Set<string>(),
      categoricalScoreNames: new Set<string>(["feedback"]),
      traceNumericScoreNames: new Set<string>(),
      traceCategoricalScoreNames: new Set<string>(),
    };
    const r = astToFilterState(parse("scores.feedback:>0.8").ast, scoreTypes);
    expect(r.errors.length).toBeGreaterThan(0);
  });

  it("rejects empty/whitespace numeric values instead of coercing to 0", () => {
    // Number("") and Number(" ") are both 0 (finite), so without an explicit
    // guard `latency:""` would silently filter for latency = 0.
    expect(lower('latency:""').errors.length).toBeGreaterThan(0);
    expect(lower('latency:" "').errors.length).toBeGreaterThan(0);
  });

  it("lowers has:/-has: to null filters", () => {
    expect(lower("has:endTime").filters).toEqual([
      { type: "null", column: "endTime", operator: "is not null", value: "" },
    ]);
    expect(lower("-has:userId").filters).toEqual([
      { type: "null", column: "userId", operator: "is null", value: "" },
    ]);
    expect(lower("has:(endTime OR userId)").errors.length).toBeGreaterThan(0);
  });

  it("lowers bare free text to searchQuery with the default scope", () => {
    // The bar emits no scope token; searchType is null and the caller applies
    // the default (ids+names+input+output). Multiple bare words are one phrase.
    const r = lower("refund policy");
    expect(r.errors).toEqual([]);
    expect(r.searchType).toBeNull();
    expect(r.searchQuery).toBe("refund policy");
    expect(r.filters).toEqual([]);
  });

  it("lowers id:/name: to contains string filters (not exact any-of)", () => {
    // id/name are textSearch now: bare `key:value` is a substring search.
    for (const column of ["id", "name"]) {
      const r = lower(`${column}:chat`);
      expect(r.errors).toEqual([]);
      expect(r.filters).toEqual([
        { type: "string", column, operator: "contains", value: "chat" },
      ]);
    }
    // `key:=value` is the explicit exact match.
    expect(lower("name:=checkout").filters).toEqual([
      {
        type: "stringOptions",
        column: "name",
        operator: "any of",
        value: ["checkout"],
      },
    ]);
    // Negation is does-not-contain (flat-representable).
    expect(lower("-id:abc").filters).toEqual([
      {
        type: "string",
        column: "id",
        operator: "does not contain",
        value: "abc",
      },
    ]);
  });

  it("lowers negated exact on id/name to stringOptions none-of (exact inequality)", () => {
    // `-name:=abc` is exact-inequality — the faithful flat form is
    // stringOptions none-of (there is no `string !=`). It is the inverse of the
    // positive `name:=abc` and the shape the facet emits when one
    // value is unchecked, so it must lower cleanly rather than error.
    for (const column of ["id", "name"]) {
      const r = lower(`-${column}:=abc`);
      expect(r.errors).toEqual([]);
      expect(r.filters).toEqual([
        { type: "stringOptions", column, operator: "none of", value: ["abc"] },
      ]);
    }
    // The commit gate accepts it (no longer a "not representable" error).
    expect(validateQuery("-name:=abc").valid).toBe(true);
  });

  it.each([
    {
      column: "ingestionApiKey",
      value: "pk-lf-1234567890",
      text: "-ingestionApiKey:pk-lf-1234567890",
    },
    { column: "name", value: "checkout", text: "-name:=checkout" },
    { column: "traceTags", value: "prod", text: "-traceTags:prod" },
  ])(
    "shows only an exclusion when the sole $column option is unchecked",
    ({ column, value, text }) => {
      const ctx: SidebarFilterActionContext = {
        facets: [{ type: "categorical", column, label: column }],
        columnDefinitions: [
          {
            id: column,
            name: column,
            type: column === "traceTags" ? "arrayOptions" : "stringOptions",
            options: [],
            internal: column,
          },
        ],
        options: { [column]: [value] },
      };
      const empty = applyCheckboxSelection(ctx, [], column, []);
      expect(empty).toEqual([
        {
          column,
          type: column === "traceTags" ? "arrayOptions" : "stringOptions",
          operator: "none of",
          value: [value],
        },
      ]);
      expect(filterStateToQueryText(empty).text).toBe(text);
      const commit = planCommit(`${text} env:prod`);
      expect(commit.status).toBe("committed");
      if (commit.status !== "committed") return;
      expect(
        commit.filters.filter((filter) => filter.column === column),
      ).toEqual(empty);
      expect(
        applyCheckboxSelection(ctx, commit.filters, column, [value]),
      ).toEqual(commit.filters.filter((filter) => filter.column !== column));
    },
  );

  it("preserves a legacy empty Name pair through a search-bar edit", () => {
    const ctx: SidebarFilterActionContext = {
      facets: [{ type: "categorical", column: "name", label: "Name" }],
      columnDefinitions: [
        {
          id: "name",
          name: "Name",
          type: "stringOptions",
          options: [],
          internal: "name",
        },
      ],
      options: { name: ["checkout", "chat"] },
    };
    const empty: FilterState = [
      {
        column: "name",
        type: "stringOptions",
        operator: "any of",
        value: ["checkout"],
      },
      {
        column: "name",
        type: "stringOptions",
        operator: "none of",
        value: ["checkout"],
      },
    ];
    const { text, skippedFilters } = filterStateToQueryText(empty);
    expect(text).toBe("name:=checkout -name:=checkout");
    expect(skippedFilters).toEqual([]);

    const commit = planCommit(`${text} env:prod`);
    expect(commit.status).toBe("committed");
    if (commit.status !== "committed") return;

    expect(commit.filters.filter((filter) => filter.column === "name")).toEqual(
      empty,
    );
    expect(hasEmptyCheckboxSelection(commit.filters, "name")).toBe(true);
    expect(
      applyCheckboxSelection(ctx, commit.filters, "name", ["chat"]),
    ).toContainEqual({
      column: "name",
      type: "stringOptions",
      operator: "any of",
      value: ["chat"],
    });
  });

  it("lowers input:/output: to real column filters (not searchType)", () => {
    const r = lower("input:refund");
    expect(r.errors).toEqual([]);
    expect(r.searchType).toBeNull();
    expect(r.filters).toEqual([
      {
        type: "string",
        column: "input",
        operator: "contains",
        value: "refund",
      },
    ]);
  });

  it("flattens parenthesized AND groups like the top-level chain", () => {
    const r = lower("(env:dev timeout)");
    expect(r.errors).toEqual([]);
    expect(r.searchQuery).toBe("timeout");
    expect(r.filters).toHaveLength(1);
  });

  it("errors instead of silently dropping unrepresentable nodes", () => {
    const cases = [
      "NOT (level:ERROR env:dev)",
      "level:ERROR OR env:dev",
      "latency:(1 OR 2)",
      "metadata.a:(x OR y)",
      "-tags:(a AND b)",
    ];
    for (const text of cases) {
      const r = lower(text);
      expect(r.errors.length, `expected errors: ${text}`).toBeGreaterThan(0);
    }
  });

  it("lowers quoted dot-path keys (score/metadata names with spaces)", () => {
    // A score or metadata name containing spaces is addressed with a quoted
    // segment after the prefix: `scores."Rouge Score"`. The quotes are stripped
    // to the real key in the lowered FilterState.
    expect(lower('scores."Rouge Score":>=1').filters).toEqual([
      {
        type: "numberObject",
        column: "scores_avg",
        key: "Rouge Score",
        operator: ">=",
        value: 1,
      },
    ]);
    expect(lower('traceScores."Hallucination Check":faithful').filters).toEqual(
      [
        {
          type: "categoryOptions",
          column: "trace_score_categories",
          key: "Hallucination Check",
          operator: "any of",
          value: ["faithful"],
        },
      ],
    );
    expect(lower('metadata."my key":eu').filters).toEqual([
      {
        type: "stringObject",
        column: "metadata",
        key: "my key",
        operator: "=",
        value: "eu",
      },
    ]);
    expect(validateQuery('scores."Rouge Score":>=1').valid).toBe(true);
  });

  it("quotes grammar-char keys in error-message example syntax", () => {
    // The suggested example syntax in diagnostics must itself parse for a
    // spaced/colon key — i.e. show the quoted form, not the bare one.
    const errsFor = (text: string) => lower(text).errors.join(" • ");
    // metadata any-of group → "supports a single value"
    expect(errsFor('metadata."my key":(a OR b)')).toContain(
      'metadata."my key"',
    );
    // negated metadata exact → suggestion quotes the key
    expect(errsFor('-metadata."my key":=foo')).toContain('-metadata."my key"');
    // numeric score any-of → "expects a single numeric value"
    expect(errsFor('scores."Rouge Score":(0.1 OR 0.2)')).toContain(
      'scores."Rouge Score"',
    );
    // string-glob op on a score → operatorIssue example quotes the key
    expect(errsFor('scores."Rouge Score":foo*')).toContain(
      'scores."Rouge Score"',
    );
  });
});

describe("validateQuery / adapter parity", () => {
  it("everything validateQuery accepts lowers without errors", () => {
    const queries = [
      "",
      "level:ERROR env:prod timeout",
      "level:(ERROR OR WARNING)",
      "-env:dev latency:>2",
      "scores.accuracy:>0.8 traceScores.nps:positive",
      "metadata.region:*eu* has:endTime -has:userId",
      "input:refund tags:(a AND b)",
      "isRootObservation:true name:*chat*",
      "(level:ERROR OR level:WARNING) env:dev",
    ];
    for (const text of queries) {
      const v = validateQuery(text);
      expect(v.valid, `expected valid: ${text}`).toBe(true);
      const r = astToFilterState(v.ast);
      expect(r.errors, `expected lowering: ${text}`).toEqual([]);
    }
  });
});

describe("filterStateToQueryText", () => {
  it("renders the experiment and evaluation exclusions as explicit filters", () => {
    expect(
      filterStateToQueryText([
        {
          column: "environment",
          type: "string",
          operator: "does not contain",
          value: "langfuse-",
        },
        {
          column: "environment",
          type: "stringOptions",
          operator: "none of",
          value: ["sdk-experiment"],
        },
        {
          column: "experimentId",
          type: "null",
          operator: "is null",
          value: "",
        },
      ]).text,
    ).toBe(
      "-environment:*langfuse-* -environment:sdk-experiment -has:experimentId",
    );
  });

  it("round-trips legacy filter state through the grammar", () => {
    const filters: FilterState = [
      {
        type: "stringOptions",
        column: "type",
        operator: "any of",
        value: ["GENERATION", "AGENT"],
      },
      {
        type: "stringOptions",
        column: "environment",
        operator: "none of",
        value: ["dev"],
      },
      { type: "number", column: "latency", operator: ">", value: 2 },
      {
        type: "string",
        column: "statusMessage",
        operator: "contains",
        value: "rate limit",
      },
      {
        type: "boolean",
        column: "isRootObservation",
        operator: "=",
        value: true,
      },
      {
        type: "stringObject",
        column: "metadata",
        key: "region",
        operator: "=",
        value: "eu",
      },
      {
        type: "numberObject",
        column: "scores_avg",
        key: "accuracy",
        operator: ">",
        value: 0.8,
      },
      {
        type: "categoryOptions",
        column: "score_categories",
        key: "feedback",
        operator: "any of",
        value: ["positive"],
      },
      {
        type: "arrayOptions",
        column: "traceTags",
        operator: "all of",
        value: ["a", "b"],
      },
      { type: "null", column: "endTime", operator: "is not null", value: "" },
    ];

    const { text, skipped } = filterStateToQueryText(filters);
    expect(skipped).toEqual([]);

    const v = validateQuery(text);
    expect(v.valid, text).toBe(true);
    const r = astToFilterState(v.ast);
    expect(r.errors).toEqual([]);
    expect(r.filters).toEqual(filters);
  });

  it("maps display-name columns and boolean <> normalization", () => {
    const filters: FilterState = [
      { type: "string", column: "User ID", operator: "=", value: "u1" },
      {
        type: "boolean",
        column: "hasParentObservation",
        operator: "<>",
        value: true,
      },
    ];
    const { text, skipped } = filterStateToQueryText(filters);
    expect(skipped).toEqual([]);
    const r = astToFilterState(validateQuery(text).ast);
    expect(r.errors).toEqual([]);
    expect(r.filters).toEqual([
      {
        type: "stringOptions",
        column: "userId",
        operator: "any of",
        value: ["u1"],
      },
      {
        type: "boolean",
        column: "hasParentObservation",
        operator: "=",
        value: false,
      },
    ]);
  });

  it("reports unrepresentable filters in skipped (descriptions + objects)", () => {
    const positionFilter: FilterState[number] = {
      type: "positionInTrace",
      column: "positionInTrace",
      operator: "=",
      key: "root",
    };
    const { text, skipped, skippedFilters } = filterStateToQueryText([
      positionFilter,
    ]);
    expect(text).toBe("");
    expect(skipped).toHaveLength(1);
    // The actual objects are surfaced so the container can preserve them
    // across a commit (no silent drop).
    expect(skippedFilters).toEqual([positionFilter]);
  });

  it("skips a single-value array all-of instead of flipping it to any-of", () => {
    // `all of [a]` has no distinct grammar form (it equals any-of, and `(a)`
    // reparses as any-of). Preserve it via skippedFilters rather than silently
    // rewrite the operator shape on commit.
    const allOfOne: FilterState[number] = {
      type: "arrayOptions",
      column: "traceTags",
      operator: "all of",
      value: ["a"],
    };
    const r = filterStateToQueryText([allOfOne]);
    expect(r.text).toBe("");
    expect(r.skippedFilters).toEqual([allOfOne]);
    // Multi-value all-of still round-trips faithfully through the AND group.
    const multi: FilterState[number] = { ...allOfOne, value: ["a", "b"] };
    const back = astToFilterState(
      parse(filterStateToQueryText([multi]).text).ast,
    );
    expect(back.filters).toEqual([multi]);
  });

  it("renders keyed filters whose key carries grammar chars via a quoted segment", () => {
    // A metadata/score key with spaces, colons, or other grammar chars is now
    // addressable with a quoted segment after the prefix (`metadata."foo:bar"`,
    // `scores."rate test"`); it round-trips instead of being skipped.
    const colonKeyMeta: FilterState[number] = {
      type: "stringObject",
      column: "metadata",
      key: "foo:bar",
      operator: "contains",
      value: "x",
    };
    const spacedScore: FilterState[number] = {
      type: "categoryOptions",
      column: "score_categories",
      key: "rate test",
      operator: "any of",
      value: ["high"],
    };
    const r = filterStateToQueryText([colonKeyMeta, spacedScore]);
    expect(r.skippedFilters).toEqual([]);
    expect(r.text).toBe('metadata."foo:bar":*x* scores."rate test":high');
    // Both round-trip back to the same FilterState.
    expect(astToFilterState(validateQuery(r.text).ast).filters).toEqual([
      colonKeyMeta,
      spacedScore,
    ]);
    // A normal key still serializes bare (contains → `*x*`).
    expect(
      filterStateToQueryText([{ ...colonKeyMeta, key: "region" }]).text,
    ).toBe("metadata.region:*x*");
  });

  it("round-trips score names with spaces (numeric + categorical, no skip)", () => {
    const numeric: FilterState = [
      {
        type: "numberObject",
        column: "scores_avg",
        key: "Rouge Score",
        operator: ">=",
        value: 1,
      },
    ];
    const numericResult = filterStateToQueryText(numeric);
    expect(numericResult.skippedFilters).toEqual([]);
    expect(numericResult.text).toBe('scores."Rouge Score":>=1');
    expect(
      astToFilterState(validateQuery(numericResult.text).ast).filters,
    ).toEqual(numeric);

    const categorical: FilterState = [
      {
        type: "categoryOptions",
        column: "trace_score_categories",
        key: "Hallucination Check",
        operator: "any of",
        value: ["faithful"],
      },
    ];
    const catResult = filterStateToQueryText(categorical);
    expect(catResult.skippedFilters).toEqual([]);
    expect(catResult.text).toBe('traceScores."Hallucination Check":faithful');
    expect(astToFilterState(validateQuery(catResult.text).ast).filters).toEqual(
      categorical,
    );
  });

  it("reverse-renders booleanObject score filters without rewriting legacy numeric filters", () => {
    const booleanFilter: FilterState = [
      {
        type: "booleanObject",
        column: "score_booleans",
        key: "Boolean Flag",
        operator: "=",
        value: true,
      },
      {
        type: "booleanObject",
        column: "trace_score_booleans",
        key: "traceFlag",
        operator: "<>",
        value: false,
      },
    ];
    expect(filterStateToQueryText(booleanFilter).text).toBe(
      'scores."Boolean Flag":true -traceScores.traceFlag:false',
    );

    expect(
      filterStateToQueryText([
        {
          type: "numberObject",
          column: "scores_avg",
          key: "Boolean Flag",
          operator: "=",
          value: 1,
        },
      ]).text,
    ).toBe('scores."Boolean Flag":1');
  });

  it("serializes metadata equality as the bare form, not :=value", () => {
    // `metadata.region:eu` lowers to a stringObject `=` filter; serializing it
    // back must produce the bare `metadata.region:eu` the user typed — the
    // explicit `metadata.region:=eu` would visibly rewrite the pill. Mirrors the
    // plain `string` exact carve-out.
    const eq: FilterState[number] = {
      type: "stringObject",
      column: "metadata",
      key: "region",
      operator: "=",
      value: "eu",
    };
    expect(filterStateToQueryText([eq]).text).toBe("metadata.region:eu");
  });

  it("serializes a textSearch contains as the bare form, not *value*", () => {
    // `input:refund` lowers to a string `contains` filter; serializing it back
    // must stay bare (`input:refund`), the documented contains-default — the
    // `input:*refund*` glob form would visibly rewrite the user's text on every
    // commit echo. Symmetric inverse of the metadata-equality carve-out.
    const contains: FilterState[number] = {
      type: "string",
      column: "input",
      operator: "contains",
      value: "refund",
    };
    expect(filterStateToQueryText([contains]).text).toBe("input:refund");
    // starts/ends-with stay as globs (no bare form expresses them).
    expect(
      filterStateToQueryText([{ ...contains, operator: "starts with" }]).text,
    ).toBe("input:refund*");
    // The NEGATED form must stay bare too (`-input:refund`, not `-input:*refund*`).
    expect(
      filterStateToQueryText([{ ...contains, operator: "does not contain" }])
        .text,
    ).toBe("-input:refund");
  });

  it("lowers content to the payload-only search lane", () => {
    expect(lower('content:"refund"')).toMatchObject({
      errors: [],
      searchQuery: "refund",
      searchType: ["content"],
      filters: [],
    });
    expect(lower("content:").errors).toEqual([]);
  });

  it("round-trips bare boolean keywords and leading-hyphen free text", () => {
    // serialize() must quote AND/OR/NOT (any case), !-prefix tokens, and -foo
    // so they reparse as free text rather than as operators/negation/reserved
    // tokens (otherwise the bar lands invalid on page load from URL state).
    for (const searchQuery of [
      "OR",
      "AND",
      "NOT",
      "-foo",
      "OR AND -x",
      "or",
      "and",
      "not",
      "team or kitten",
      "test not really",
      "!important",
      "!critical bug",
    ]) {
      const { text } = filterStateToQueryText([], { searchQuery });
      const v = validateQuery(text);
      expect(v.valid, `${searchQuery} -> ${text}`).toBe(true);
      const r = astToFilterState(v.ast);
      expect(r.errors).toEqual([]);
      expect(r.searchQuery).toBe(searchQuery);
    }
  });

  it("keeps a residual input search in its backend lane", () => {
    const { text } = filterStateToQueryText([], {
      searchQuery: "refund policy",
      searchType: ["input"],
    });
    expect(text).toBe('in:input "refund policy"');
    expect(planCommit(text)).toMatchObject({
      status: "committed",
      filters: [],
      searchQuery: "refund policy",
      searchType: ["input"],
    });
  });

  it("only renders the exact default scope as bare text", () => {
    expect(
      filterStateToQueryText([], {
        searchQuery: "hello",
        searchType: ["id", "content"],
      }).text,
    ).toBe("hello");
    expect(
      filterStateToQueryText([], {
        searchQuery: "hello",
        searchType: ["content"],
      }).text,
    ).toBe("content:hello");
    expect(
      filterStateToQueryText([], {
        searchQuery: "hello",
        searchType: ["id"],
      }).text,
    ).toBe("in:id hello");
  });

  it("preserves EXACT semantics for a single-value stringOptions any-of on id/name", () => {
    // id/name are stringOptions columns in eventsTable (the facet sidebar emits
    // this shape), but textSearch fields in the bar. A single-value any-of must
    // NOT silently re-lower to `contains` — it must keep exact-match semantics.
    for (const column of ["id", "name"]) {
      const filters: FilterState = [
        { type: "stringOptions", column, operator: "any of", value: ["abc"] },
      ];
      const { text, skipped } = filterStateToQueryText(filters);
      expect(skipped).toEqual([]);
      expect(text).toBe(`${column}:=abc`); // explicit exact, not bare `id:abc`
      const r = astToFilterState(validateQuery(text).ast);
      // Name retains its categorical facet shape; ID uses string equality.
      const expected =
        column === "name"
          ? filters
          : [{ type: "string", column, operator: "=", value: "abc" }];
      expect(r.filters).toEqual(expected);
      // And the stabilized form is a fixpoint (no further drift).
      const echo = filterStateToQueryText(r.filters);
      expect(echo.text).toBe(`${column}:=abc`);
    }
  });

  it("round-trips a multi-value stringOptions any-of on id/name losslessly", () => {
    const filters: FilterState = [
      {
        type: "stringOptions",
        column: "id",
        operator: "any of",
        value: ["a", "b"],
      },
    ];
    const { text, skipped } = filterStateToQueryText(filters);
    expect(skipped).toEqual([]);
    expect(astToFilterState(validateQuery(text).ast).filters).toEqual(filters);
  });

  it("renders a single-value stringOptions none-of on id/name as negated exact", () => {
    // A single none-of on a textSearch field is exact-inequality. The faithful
    // grammar form is the negated exact `-name:=abc` (which lowers back to
    // stringOptions none-of), NOT `-name:abc` (does-not-contain / substring).
    // This is the facet "uncheck one value" shape — it must render in the bar,
    // not vanish into skippedFilters.
    for (const column of ["id", "name"]) {
      const filters: FilterState = [
        {
          type: "stringOptions",
          column,
          operator: "none of",
          value: ["abc"],
        },
      ];
      const { text, skipped, skippedFilters } = filterStateToQueryText(filters);
      expect(skipped).toEqual([]);
      expect(skippedFilters).toEqual([]);
      expect(text).toBe(`-${column}:=abc`);
      // And it round-trips back to the same stringOptions none-of filter.
      expect(astToFilterState(validateQuery(text).ast).filters).toEqual(
        filters,
      );
    }
  });

  it("round-trips option values with operator-prefix, keyword, and empty forms", () => {
    const filters: FilterState = [
      {
        type: "stringOptions",
        column: "name",
        operator: "any of",
        value: [">weird", "OR", "", "normal"],
      },
    ];
    const { text, skipped } = filterStateToQueryText(filters);
    expect(skipped).toEqual([]);
    const v = validateQuery(text);
    expect(v.valid, text).toBe(true);
    expect(astToFilterState(v.ast).filters).toEqual(filters);
  });

  it("quotes free-text terms that carry grammar characters", () => {
    const { text } = filterStateToQueryText([], {
      searchQuery: "a:b (c)",
    });
    const v = validateQuery(text);
    expect(v.valid, text).toBe(true);
    const r = astToFilterState(v.ast);
    expect(r.filters).toEqual([]);
    expect(r.searchQuery).toBe("a:b (c)");
  });

  it("preserves a multi-space free-text phrase (no \\s+ collapse)", () => {
    const { text } = filterStateToQueryText([], {
      searchQuery: "hello   world",
    });
    const r = astToFilterState(validateQuery(text).ast);
    expect(r.searchQuery).toBe("hello   world");
  });

  it("renders a default multi-word phrase as ONE quoted token, not split terms", () => {
    // A default-scope searchQuery is a contiguous-substring phrase (ILIKE
    // %query%), so it derives to a single quoted token — consistent with the
    // scope-rewrite suggestions and preserving the user's quotes — rather than
    // whitespace-split bare terms that read as independent AND filters.
    expect(
      filterStateToQueryText([], { searchQuery: "abc abc abc" }).text,
    ).toBe('"abc abc abc"');
    // A single word needs no quotes.
    expect(filterStateToQueryText([], { searchQuery: "abc" }).text).toBe("abc");
    // Still round-trips to the same phrase.
    const r = astToFilterState(
      validateQuery(
        filterStateToQueryText([], { searchQuery: "abc abc abc" }).text,
      ).ast,
    );
    expect(r.searchQuery).toBe("abc abc abc");
  });

  it('round-trips an empty-value metadata filter (:="")', () => {
    const filters: FilterState = [
      {
        type: "stringObject",
        column: "metadata",
        key: "region",
        operator: "=",
        value: "",
      },
    ];
    const { text, skipped } = filterStateToQueryText(filters);
    expect(skipped).toEqual([]);
    const v = validateQuery(text);
    expect(v.valid, text).toBe(true);
    expect(astToFilterState(v.ast).filters).toEqual(filters);
  });
});