Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

10.8 KB
Raw Blame
import { describe, expect, it } from "vitest";

import {
  evaluateQuery,
  explainLine,
  learnQuery,
  lineChoices,
  queryTotalCount,
  renderQueryList,
  type QueryLine,
} from "./environmentStateListQuery.js";
import { singleQueryValues } from "../recordedTransportUrl.js";
import type { JsonObject, StateEntity } from "./environmentStateRules.js";

const entity = (fields: JsonObject): StateEntity => ({
  type: "/api/books",
  collection: "/api/books",
  id: String(fields["id"]),
  fields,
  view_fields: [],
  record_ordinals: [],
});

const BOOKS = [
  {
    id: 1,
    name: "Tide Tables",
    shelf: "a",
    tags: ["sea"],
    url: "https://x/tide",
  },
  { id: 2, name: "Lamp Oil", shelf: "b", tags: [{ id: "t1", name: "oil" }] },
  { id: 3, name: "tidewater", shelf: "a", tags: [], url: "https://x/other" },
  {
    id: 4,
    name: "Kelp",
    shelf: null,
    tags: ["sea"],
    url: "https://x/kelp-tide",
  },
].map((book) => entity({ ...book, active: true }));

/** A line as the gate reads it: its query, and the books it listed in order. */
const line = (
  query: string,
  listed: readonly number[],
  ordinal = 0,
): QueryLine => {
  const values = singleQueryValues(query)!;
  const items = listed.map(
    (id) => BOOKS.find((book) => book.id === String(id))!.fields,
  );
  return {
    ordinal,
    values,
    listed: listed.map(String),
    choices: lineChoices(values, items),
    entities: BOOKS,
  };
};

const ids = (query: string, parameters: Parameters<typeof evaluateQuery>[0]) =>
  evaluateQuery(parameters, singleQueryValues(query)!, BOOKS)?.page.map(
    (book) => book.id,
  );

describe("explaining a recorded line", () => {
  it("finds a filter on the field every listed item holds, scalar or in an array", () => {
    expect(explainLine(line("?shelf=a", [1, 3]))).toEqual({
      shelf: { role: "filter", field: "shelf" },
    });
    expect(explainLine(line("?tag=sea", [1, 4]))).toEqual({
      tag: { role: "filter", field: "tags" },
    });
    expect(explainLine(line("?tag=t1", [2]))).toEqual({
      tag: { role: "filter", field: "tags" },
    });
  });

  it("searches the fields the term matched, ignoring case, and leaves out URLs that merely repeat it", () => {
    expect(explainLine(line("?q=TIDE", [1, 3]))).toEqual({
      q: { role: "search", fields: ["name"] },
    });
  });

  it("sorts by the field a value names, with a direction parameter, prefix or suffix", () => {
    expect(
      explainLine(line("?orderBy=name&orderDirection=desc", [3, 1, 2, 4])),
    ).toEqual({
      orderBy: { role: "sort" },
      orderDirection: { role: "direction" },
    });
    expect(ids("?sort=-name", { sort: { role: "sort" } })).toEqual([
      "3",
      "1",
      "2",
      "4",
    ]);
    expect(ids("?sort=NAME-asc", { sort: { role: "sort" } })).toEqual([
      "4",
      "2",
      "1",
      "3",
    ]);
    // Null values sort last ascending.
    expect(ids("?sort=shelf", { sort: { role: "sort" } })).toEqual([
      "1",
      "3",
      "2",
      "4",
    ]);
  });

  it("pages by limit and offset, or by page number from the first page it explains", () => {
    expect(explainLine(line("?limit=2&offset=1", [2, 3]))).toEqual({
      limit: { role: "limit" },
      offset: { role: "offset" },
    });
    expect(explainLine(line("?page=2&per_page=2", [3, 4]))).toEqual({
      page: { role: "page", first: 1 },
      per_page: { role: "limit" },
    });
    expect(ids("?per_page=-1", { per_page: { role: "limit" } })).toEqual([
      "1",
      "2",
      "3",
      "4",
    ]);
  });

  it("takes a parameter that changes nothing as inert, for its recorded values only", () => {
    const explained = explainLine(line("?includeDeleted=true", [1, 2, 3, 4]));
    expect(explained).toEqual({
      includeDeleted: { role: "inert", values: ["true"] },
    });
    expect(ids("?includeDeleted=false", explained!)).toBeUndefined();
  });

  it("leaves ambiguous page conventions unknown rather than preferring the first candidate", () => {
    expect(explainLine(line("?page=100&limit=1", []))).toBeUndefined();
    expect(explainLine(line("?page=0&limit=2", [1, 2]))).toEqual({
      page: { role: "page", first: 0 },
      limit: { role: "limit" },
    });
    expect(explainLine(line("?limit=2&page=2", [3, 4]))).toEqual({
      limit: { role: "limit" },
      page: { role: "page", first: 1 },
    });
  });

  it.each(["title:Tide", "#sea", '"Tide Tables"', "Tide OR Oil", "+Tide"])(
    "does not infer a literal substring model for search syntax: %s",
    (term) => {
      expect(
        explainLine(line(`?q=${encodeURIComponent(term)}`, [1, 2, 3, 4])),
      ).toBeUndefined();
      expect(
        ids(`?q=${encodeURIComponent(term)}`, {
          q: { role: "search", fields: ["name"] },
        }),
      ).toBeUndefined();
    },
  );

  it("uses safe numeric precision rather than an arbitrary digit-count limit", () => {
    expect(ids("?offset=1000000000", { offset: { role: "offset" } })).toEqual(
      [],
    );
    expect(
      ids("?limit=9007199254740991", { limit: { role: "limit" } }),
    ).toEqual(["1", "2", "3", "4"]);
    expect(
      ids("?offset=9007199254740992", { offset: { role: "offset" } }),
    ).toBeUndefined();
    expect(explainLine(line("?offset=unknown", [1, 2, 3, 4]))).toBeUndefined();
  });

  it("keeps a filter that excludes nothing inert, as a flag", () => {
    expect(explainLine(line("?active=true", [1, 2, 3, 4]))).toEqual({
      active: { role: "inert", values: ["true"] },
    });
  });

  it("explains nothing that the collection cannot reproduce", () => {
    expect(explainLine(line("?shelf=a", [3, 1]))).toBeUndefined();
  });
});

describe("learning a list's query", () => {
  it("joins lines into one role per parameter and answers the lines it reproduces", () => {
    const learned = learnQuery([
      line("?shelf=a", [1, 3], 10),
      line("?shelf=b", [2], 11),
      line("?q=kelp", [4], 12),
      line("?q=oil", [2], 13),
    ]);
    expect(learned).toEqual({
      parameters: {
        shelf: { role: "filter", field: "shelf" },
        q: { role: "search", fields: ["name"] },
      },
      record_ordinals: [10, 11, 12, 13],
    });
    // A value no line recorded is evaluated the same way.
    expect(ids("?q=TIDE&shelf=a", learned!.parameters)).toEqual(["1", "3"]);
  });

  it("refuses a value a parameter cannot apply, or a parameter it never learned", () => {
    const parameters = { limit: { role: "limit" } } as const;
    expect(ids("?limit=two", parameters)).toBeUndefined();
    expect(ids("?shelf=a", parameters)).toBeUndefined();
    expect(singleQueryValues("?a=1&a=2")).toBeUndefined();
  });

  it("normalizes identical repeats as serving does, retaining conflicting values as unknown", () => {
    expect(singleQueryValues("?shelf=a&shelf=%61")).toEqual(
      new Map([["shelf", "a"]]),
    );
    expect(singleQueryValues("?shelf=a&shelf=b")).toBeUndefined();
  });

  it("gives no two parameters one paging role, which would answer differently in serving's name order", () => {
    const both = { size: { role: "limit" }, limit: { role: "limit" } } as const;
    expect(ids("?size=2&limit=1", both)).toBeUndefined();
    const learned = learnQuery([line("?size=2&limit=1", [1], 40)]);
    expect(learned?.parameters).toEqual({
      size: { role: "inert", values: ["2"] },
      limit: { role: "limit" },
    });
    // Serving supplies a call's values in name order.
    expect(ids("?limit=1&size=2", learned!.parameters)).toEqual(["1"]);
  });
});

describe("queries the state can always answer", () => {
  it("models only reproducible total representations, without losing their source type", () => {
    for (const value of [
      0,
      3,
      "0",
      "3",
      Number.MAX_SAFE_INTEGER,
      String(Number.MAX_SAFE_INTEGER),
    ])
      expect(queryTotalCount(value)).toBe(Number(value));
    for (const value of [
      null,
      "unknown",
      "03",
      "3.0",
      " 3",
      "-1",
      -1,
      1.5,
      "9007199254740992",
    ])
      expect(queryTotalCount(value)).toBeUndefined();
    const view = {
      pointer: "/items",
      counters: [],
      query: { totals: ["total"] },
    };
    expect(renderQueryList(view, { items: [], total: "3" }, [], 2)).toEqual({
      items: [],
      total: "2",
    });
    expect(renderQueryList(view, { items: [], total: "03" }, [], 2)).toEqual({
      items: [],
      total: "03",
    });
  });

  it("projects query totals only into envelopes that actually contain a known count", () => {
    const view = {
      pointer: "/items",
      counters: ["numberOfElements"],
      query: { totals: ["total"] },
    };
    const selected = [{ id: 1 }];
    expect(
      renderQueryList(view, { items: [], numberOfElements: 0 }, selected, 7),
    ).toEqual({ items: selected, numberOfElements: 1 });
    expect(
      renderQueryList(view, { items: [], total: null }, selected, 7),
    ).toEqual({ items: selected, total: null });
    expect(renderQueryList(view, { items: [], total: 3 }, selected, 7)).toEqual(
      { items: selected, total: 7 },
    );
  });

  it("sorts case-only ties in state order, ignoring case", () => {
    const named = [
      entity({ id: 10, name: "alpha" }),
      entity({ id: 11, name: "Alpha" }),
    ];
    const order = (entities: readonly StateEntity[]) =>
      evaluateQuery(
        { sort: { role: "sort" } },
        singleQueryValues("?sort=name")!,
        entities,
      )?.page.map((entry) => entry.id);
    expect(order(named)).toEqual(["10", "11"]);
    expect(order([...named].reverse())).toEqual(["11", "10"]);
  });

  it("answers a sort of an emptied collection with no entities rather than giving up", () => {
    expect(
      evaluateQuery(
        { sort: { role: "sort" } },
        singleQueryValues("?sort=-id")!,
        [],
      ),
    ).toEqual({ page: [], total: 0, positional: "all" });
  });

  it("learns no search from a term that matched no field, keeping it inert", () => {
    const learned = learnQuery([line("?q=", [1, 2, 3, 4], 20)]);
    expect(learned?.parameters["q"]).toEqual({ role: "inert", values: [""] });
  });

  it("explains no line with more query names than it can search, without exhausting the stack", () => {
    const values = new Map(
      Array.from({ length: 5_000 }, (_, index) => [`p${String(index)}`, "x"]),
    );
    const choices = lineChoices(
      values,
      BOOKS.map((entry) => entry.fields),
    );
    expect(choices).toEqual([]);
    expect(
      explainLine({ ordinal: 0, values, listed: [], choices, entities: BOOKS }),
    ).toBeUndefined();
  });

  it("keeps a parameter named like an object's prototype as its own role", () => {
    const learned = learnQuery([line("?__proto__=x&shelf=a", [1, 3], 30)]);
    expect(Object.keys(learned!.parameters)).toContain("__proto__");
    const round = JSON.parse(JSON.stringify(learned!.parameters)) as object;
    expect(Object.getOwnPropertyDescriptor(round, "__proto__")?.value).toEqual({
      role: "inert",
      values: ["x"],
    });
  });
});