HealthLog/src/__tests__/list-page-guard.test.ts

/**
 * Structural guard: every capped or paged list gets its page from one helper,
 * and every such read has a total order.
 *
 * The list routes had five answers to "is there more", and two of them lied:
 * a `hasMore` computed as `rows.length === limit` reported more on a page that
 * was exactly full, and a list cut at its `take` with no signal at all let the
 * last row read as the oldest one there is. `listPage`
 * (`src/lib/http/list-query.ts`) reads one row past the limit and says
 * exactly whether that row exists. This guard holds the tree to it:
 *
 *   1. a route that answers with `apiListSuccess` gets its cap from
 *      `listPage`;
 *   2. nothing outside the two list modules calls `capRows` or `overfetch` by
 *      hand;
 *   3. a `hasMore` is never a length comparison;
 *   4. every read passed to `listPage` orders by something that ends in the
 *      row id, so a page boundary between two rows that share a sort value
 *      neither repeats one nor drops one.
 *
 * The routes are derived from the tree, never listed by hand. Comments are
 * stripped first, and the planted cases at the top prove each matcher fires.
 */
import { readFileSync } from "node:fs";
import { join } from "node:path";
import { describe, expect, it } from "vitest";

import { stripComments, walkSourceFiles } from "./helpers/source-files";

const SRC = join(process.cwd(), "src");

/** The modules allowed to cut a list by hand: the helper and its primitive. */
const LIST_MODULES = new Set([
  "lib/api/list-cap.ts",
  "lib/http/list-query.ts",
  // The MCP tools' name for `listPage`; its reads are checked at its callers.
  "lib/mcp/capped.ts",
]);

/** The text of a call's argument list, from the `(` after `name` to its match. */
function callBodies(code: string, name: string): string[] {
  const out: string[] = [];
  const re = new RegExp(`\\b${name}\\s*\\(`, "g");
  for (let m = re.exec(code); m; m = re.exec(code)) {
    let depth = 0;
    let i = m.index + m[0].length - 1;
    const start = i;
    for (; i < code.length; i++) {
      const ch = code[i];
      if (ch === "(") depth++;
      else if (ch === ")") {
        depth--;
        if (depth === 0) break;
      }
    }
    out.push(code.slice(start, i + 1));
  }
  return out;
}

/** The value of the first `orderBy` in a read, up to its closing bracket. */
function orderByValue(body: string): string | null {
  const m = /\borderBy\b\s*(:)?\s*/.exec(body);
  if (!m) return null;
  // Shorthand `orderBy,` names a variable of the same name.
  if (!m[1]) return "orderBy";
  let i = m.index + m[0].length;
  const open = body[i];
  if (open !== "[" && open !== "{") {
    const ident = /^[A-Za-z_$][\w$]*/.exec(body.slice(i));
    return ident ? ident[0] : null;
  }
  const close = open === "[" ? "]" : "}";
  let depth = 0;
  const start = i;
  for (; i < body.length; i++) {
    if (body[i] === open) depth++;
    else if (body[i] === close) {
      depth--;
      if (depth === 0) break;
    }
  }
  return body.slice(start, i + 1);
}

/** Whether an order ends in the row id, following one variable if named. */
function endsInId(order: string, file: string): boolean {
  const literal = (text: string) =>
    /^\[[\s\S]*\{\s*id\s*:\s*[^}]+\}\s*,?\s*\]$/.test(text.trim());
  if (order.startsWith("[") || order.startsWith("{")) return literal(order);
  const decl = new RegExp(
    `\\b(?:const|let)\\s+${order}\\b[^=]*=\\s*(\\[[\\s\\S]*?\\]);`,
  ).exec(file);
  return decl ? literal(decl[1]) : false;
}

/**
 * A `distinct` read returns one row per key, so ordering by that key alone is
 * already total: `distinct: ["analyte"]` with `orderBy: { analyte: "asc" }`.
 */
function ordersByDistinctKey(body: string, order: string): boolean {
  const distinct = /\bdistinct\s*:\s*\[\s*["'](\w+)["']\s*\]/.exec(body);
  if (!distinct) return false;
  return new RegExp(`^\\{\\s*${distinct[1]}\\s*:[^,}]+\\}$`).test(order.trim());
}

describe("capped lists go through listPage", () => {
  const files = walkSourceFiles(SRC, { floor: 3000 }).filter(
    (file) =>
      !file.startsWith("generated/") &&
      !file.includes("__tests__/") &&
      !/\.test\.tsx?$/.test(file),
  );
  const read = (file: string) =>
    stripComments(readFileSync(join(SRC, file), "utf8"));
  const routes = files.filter((f) => /^app\/api\/.+\/route\.tsx?$/.test(f));

  it("the matchers fire on planted sources", () => {
    const handRolled = `
      const found = await prisma.allergy.findMany({ take: overfetch(limit) });
      const { rows, cap } = capRows(found, limit);
      return apiListSuccess(rows, cap);`;
    expect(/\bcapRows\s*\(/.test(handRolled)).toBe(true);
    expect(/\blistPage\s*\(/.test(handRolled)).toBe(false);

    expect(
      /\bhasMore\s*:[^,\n]*\.length\b/.test(
        "hasMore: rows.length === q.limit,",
      ),
    ).toBe(true);
    expect(
      /\bhasMore\s*:[^,\n]*\.length\b/.test("hasMore: cap.truncated,"),
    ).toBe(false);

    const noTiebreak = `listPage(limit, (take) =>
      prisma.x.findMany({ orderBy: { createdAt: "desc" }, take }))`;
    const [body] = callBodies(noTiebreak, "listPage");
    expect(endsInId(orderByValue(body)!, noTiebreak)).toBe(false);

    const tiebreak = `listPage(limit, (take) =>
      prisma.x.findMany({ orderBy: [{ createdAt: "desc" }, { id: "desc" }], take }))`;
    const [good] = callBodies(tiebreak, "listPage");
    expect(endsInId(orderByValue(good)!, tiebreak)).toBe(true);

    // A shorthand `orderBy` resolves through its declaration.
    const viaVariable = `const orderBy: X[] = [primaryOrder, { id: order }];
      listPage(limit, (take) => prisma.x.findMany({ where, orderBy, take }))`;
    const [short] = callBodies(viaVariable, "listPage");
    expect(endsInId(orderByValue(short)!, viaVariable)).toBe(true);
    // A distinct read is ordered whole by its own key.
    const distinctRead = `listPage(limit, (take) =>
      prisma.x.findMany({ distinct: ["analyte"], orderBy: { analyte: "asc" }, take }))`;
    const [dist] = callBodies(distinctRead, "listPage");
    expect(ordersByDistinctKey(dist, orderByValue(dist)!)).toBe(true);
    expect(ordersByDistinctKey(dist, '{ createdAt: "desc" }')).toBe(false);
    const viaBadVariable = `const orderBy = [primaryOrder];
      listPage(limit, (take) => prisma.x.findMany({ where, orderBy, take }))`;
    const [bad] = callBodies(viaBadVariable, "listPage");
    expect(endsInId(orderByValue(bad)!, viaBadVariable)).toBe(false);
  });

  it("finds the capped routes", () => {
    const capped = routes.filter((f) => /\bapiListSuccess\s*\(/.test(read(f)));
    expect(capped.length).toBeGreaterThanOrEqual(15);
  });

  it("every route answering a capped list gets its cap from listPage", () => {
    const unbound = routes.filter((f) => {
      const code = read(f);
      return (
        /\bapiListSuccess\s*\(/.test(code) && !/\blistPage\s*\(/.test(code)
      );
    });
    expect(unbound).toEqual([]);
  });

  it("nothing cuts a list by hand outside the list modules", () => {
    const handRolled = files.filter(
      (f) =>
        !LIST_MODULES.has(f) && /\b(?:capRows|overfetch)\s*\(/.test(read(f)),
    );
    expect(handRolled).toEqual([]);
  });

  it("no hasMore is a length comparison", () => {
    const guessed = routes.filter((f) =>
      /\bhasMore\s*:[^,\n]*\.length\b/.test(read(f)),
    );
    expect(guessed).toEqual([]);
  });

  it("every listPage or capped read orders by something that ends in the row id", () => {
    const unordered: string[] = [];
    let reads = 0;
    for (const f of files) {
      if (LIST_MODULES.has(f)) continue;
      const code = read(f);
      for (const body of [
        ...callBodies(code, "listPage"),
        ...callBodies(code, "capped"),
      ]) {
        reads += 1;
        const order = orderByValue(body);
        if (
          !order ||
          !(endsInId(order, code) || ordersByDistinctKey(body, order))
        ) {
          unordered.push(f);
        }
      }
    }
    expect(reads).toBeGreaterThanOrEqual(18);
    expect(unordered).toEqual([]);
  });
});