@jant/core 0.6.16 → 0.7.1

package/src/__tests__/snapshot-tables.test.ts

@@ -0,0 +1,219 @@
+/**
+ * Snapshot Table Registry Guard
+ *
+ * `jant site snapshot export/import` walks two hand-written arrays in
+ * `bin/lib/site-snapshot.js`. Nothing connects them to `db/schema.ts`: `bin/`
+ * is plain JavaScript, outside the type system, so a new site-scoped table
+ * compiles, lints and tests clean while the snapshot silently skips it.
+ *
+ * That already happened. `smart_collection` arrived with migration 0033, and
+ * the commit that added it updated the schema, both dialects, five services, a
+ * route and three test files — but not these arrays. The damage was silent in
+ * both directions: export dropped smart collections, and `--replace` could not
+ * delete the ones a visitor created, so they outlived every nightly demo
+ * rebuild as rows with no slug and no nav entry.
+ *
+ * These tests close the gap. Every site-scoped table has to be named in one of
+ * the two registries, so a new table forces a decision instead of defaulting to
+ * "forgotten". The order assertions pin the arrays' other implicit contract:
+ * `SNAPSHOT_TABLES` is an INSERT order and `SNAPSHOT_CLEAR_TABLES` is a DELETE
+ * order, and both have to respect foreign keys — which are enforced, on D1 and
+ * on Node alike (`bin/lib/node-sqlite.js` sets `foreign_keys = ON`).
+ *
+ * Reading `db/schema.ts` alone covers both dialects: the registries are shared
+ * (only the dumped SQL is dialect-specific), and `db/pg/schema.ts` is required
+ * to declare the same tables.
+ */
+
+import { is } from "drizzle-orm";
+import { SQLiteTable, getTableConfig } from "drizzle-orm/sqlite-core";
+import { describe, expect, it } from "vitest";
+import {
+  SNAPSHOT_CLEAR_TABLES,
+  SNAPSHOT_EXCLUDED_TABLES,
+  SNAPSHOT_TABLES,
+  getSnapshotSelectSql,
+} from "../../bin/lib/site-snapshot.js";
+import {
+  TABLE_EXPORT_ORDER,
+  sortExportTables,
+} from "../../bin/lib/sql-export.js";
+import * as schema from "../db/schema.js";
+
+/** `site_setting` is cleared by key, not wholesale — see `buildReplaceSql`. */
+const CLEARED_BY_KEY = "site_setting";
+
+type SchemaTable = {
+  /** Physical table name, as it appears in SQL. */
+  name: string;
+  /** Tables this one points at with a foreign key, excluding self-references. */
+  dependsOn: string[];
+};
+
+/**
+ * Reads every site-scoped table out of the Drizzle schema with its foreign-key
+ * dependencies. "Site-scoped" means the table carries a `site_id` column, which
+ * is what makes a row belong to one site's content rather than the instance.
+ *
+ * @returns One entry per site-scoped table, in declaration order.
+ */
+function readSiteScopedTables(): SchemaTable[] {
+  const tables: SchemaTable[] = [];
+
+  for (const exported of Object.values(schema)) {
+    if (!is(exported, SQLiteTable)) continue;
+    const config = getTableConfig(exported);
+    if (!config.columns.some((column) => column.name === "site_id")) continue;
+
+    const dependsOn = [
+      ...new Set(
+        config.foreignKeys.map(
+          (foreignKey) =>
+            getTableConfig(foreignKey.reference().foreignTable).name,
+        ),
+      ),
+    ].filter((target) => target !== config.name);
+
+    tables.push({ name: config.name, dependsOn });
+  }
+
+  return tables;
+}
+
+const siteScopedTables = readSiteScopedTables();
+const siteScopedNames = siteScopedTables.map((table) => table.name);
+
+describe("snapshot table registry", () => {
+  it("covers every site-scoped table as content or an explicit exclusion", () => {
+    const registered = new Set<string>([
+      ...SNAPSHOT_TABLES,
+      ...SNAPSHOT_EXCLUDED_TABLES,
+    ]);
+    const unregistered = siteScopedNames.filter(
+      (name) => !registered.has(name),
+    );
+
+    expect(
+      unregistered,
+      [
+        "These site-scoped tables are in db/schema.ts but in neither snapshot registry.",
+        "A table the snapshot does not know about is dropped on export and survives",
+        "`--replace` on import. Add it to SNAPSHOT_TABLES if it is site content, or to",
+        "SNAPSHOT_EXCLUDED_TABLES with the reason if it is shell, credential or",
+        "transient state, in bin/lib/site-snapshot.js.",
+      ].join("\n"),
+    ).toEqual([]);
+  });
+
+  it("does not register a table as both content and excluded", () => {
+    const excluded = new Set<string>(SNAPSHOT_EXCLUDED_TABLES);
+    const both = SNAPSHOT_TABLES.filter((name) => excluded.has(name));
+
+    expect(both).toEqual([]);
+  });
+
+  it("can build an export query for every content table", () => {
+    // `getSnapshotSelectSql` has no default branch: a table listed as content
+    // without a matching statement throws "Unsupported snapshot table" at
+    // export time, which is the same silent-until-used failure the registry
+    // itself had.
+    for (const table of SNAPSHOT_TABLES) {
+      expect(() =>
+        getSnapshotSelectSql(table, "sit_00000000000000000000000000"),
+      ).not.toThrow();
+    }
+  });
+
+  it("does not keep registry entries for tables the schema dropped", () => {
+    const known = new Set(siteScopedNames);
+    const stale = [...SNAPSHOT_TABLES, ...SNAPSHOT_EXCLUDED_TABLES].filter(
+      (name) => !known.has(name),
+    );
+
+    expect(stale).toEqual([]);
+  });
+});
+
+describe("snapshot table ordering", () => {
+  it("registers every content table for export ordering", () => {
+    // A table missing here is not merely unordered: `sortExportTables` places
+    // unknown names after every known one, so a new child table is dumped
+    // behind its own parents and the import fails the first time a row exists
+    // to violate the constraint.
+    const ordered = new Set<string>(TABLE_EXPORT_ORDER);
+    expect(SNAPSHOT_TABLES.filter((name) => !ordered.has(name))).toEqual([]);
+  });
+
+  it("inserts a table only after every table it references", () => {
+    // The order an export actually follows. `SNAPSHOT_TABLES` is re-sorted by
+    // `TABLE_EXPORT_ORDER` on the way out, so asserting on the raw list would
+    // check something the dump ignores.
+    const position = new Map(
+      sortExportTables(SNAPSHOT_TABLES).map((name, index) => [name, index]),
+    );
+    const violations: string[] = [];
+
+    for (const table of siteScopedTables) {
+      const self = position.get(table.name);
+      if (self === undefined) continue;
+
+      for (const dependency of table.dependsOn) {
+        const parent = position.get(dependency);
+        if (parent === undefined) continue;
+        if (parent > self) {
+          violations.push(
+            `${table.name} (${self}) references ${dependency} (${parent})`,
+          );
+        }
+      }
+    }
+
+    expect(
+      violations,
+      [
+        "TABLE_EXPORT_ORDER in sql-export.js is the order rows are dumped, and so the",
+        "order they are inserted on import. A table has to come after everything it",
+        "points at with a foreign key, or the child row lands before its parent exists",
+        "and the insert fails the constraint.",
+      ].join("\n"),
+    ).toEqual([]);
+  });
+
+  it("deletes a table before every table it references", () => {
+    const position = new Map(
+      SNAPSHOT_CLEAR_TABLES.map((name, index) => [name, index]),
+    );
+    const violations: string[] = [];
+
+    for (const table of siteScopedTables) {
+      const self = position.get(table.name);
+      if (self === undefined) continue;
+
+      for (const dependency of table.dependsOn) {
+        const parent = position.get(dependency);
+        if (parent === undefined) continue;
+        if (parent < self) {
+          violations.push(
+            `${table.name} (${self}) references ${dependency} (${parent})`,
+          );
+        }
+      }
+    }
+
+    expect(
+      violations,
+      [
+        "SNAPSHOT_CLEAR_TABLES is the order rows are deleted by `--replace`, so a table",
+        "has to come before everything it points at. Deleting the parent first only",
+        "appears to work because the cascade takes the children with it — which is",
+        "implicit, and stops being true the moment a reference is not ON DELETE CASCADE.",
+      ].join("\n"),
+    ).toEqual([]);
+  });
+
+  it("clears every content table except the one cleared by key", () => {
+    expect([...SNAPSHOT_CLEAR_TABLES].sort()).toEqual(
+      SNAPSHOT_TABLES.filter((name) => name !== CLEARED_BY_KEY).sort(),
+    );
+  });
+});

package/src/__tests__/sql-export.test.ts

@@ -0,0 +1,173 @@
+/**
+ * The SQL dump behind `db export` and `site snapshot export`.
+ *
+ * On D1 every query goes through `wrangler d1 execute --json`, whose output
+ * the CLI buffers. One `SELECT *` of a real site's `post` table overflowed
+ * that buffer, so the dump reads D1 a page at a time.
+ */
+
+import { describe, expect, it } from "vitest";
+import Database from "better-sqlite3";
+import { dumpDatabaseToSql } from "../../bin/lib/sql-export.js";
+import { orderSnapshotPostRows } from "../../bin/lib/site-snapshot.js";
+import { describeWranglerFailure } from "../../bin/lib/d1-query.js";
+import { WRANGLER_MAX_BUFFER } from "../../bin/lib/wrangler-cli.js";
+
+function createQueryRunner() {
+  const db = new Database(":memory:");
+  db.exec(`
+    CREATE TABLE "post" ("id" TEXT PRIMARY KEY, "site_id" TEXT, "body" TEXT);
+  `);
+  const insert = db.prepare(
+    `INSERT INTO "post" ("id", "site_id", "body") VALUES (?, ?, ?)`,
+  );
+  for (let index = 0; index < 7; index += 1) {
+    insert.run(`pst_${index}`, "site", `body ${index}`);
+  }
+
+  const statements: string[] = [];
+  return {
+    statements,
+    runner: {
+      async query(sql: string) {
+        statements.push(sql);
+        return db.prepare(sql).all() as Record<string, unknown>[];
+      },
+    },
+  };
+}
+
+describe("dumpDatabaseToSql", () => {
+  it("reads a table in pages when given a page size", async () => {
+    const { runner, statements } = createQueryRunner();
+
+    const sql = await dumpDatabaseToSql(runner, {
+      source: "local",
+      dialect: "sqlite",
+      tables: ["post"],
+      pageSize: 3,
+    });
+
+    const reads = statements.filter((statement) =>
+      statement.includes('FROM "post"'),
+    );
+    expect(reads).toEqual([
+      'SELECT * FROM "post" ORDER BY rowid LIMIT 3 OFFSET 0',
+      'SELECT * FROM "post" ORDER BY rowid LIMIT 3 OFFSET 3',
+      'SELECT * FROM "post" ORDER BY rowid LIMIT 3 OFFSET 6',
+    ]);
+    for (let index = 0; index < 7; index += 1) {
+      expect(sql).toContain(`'pst_${index}'`);
+    }
+  });
+
+  it("pages a table's own ordered select", async () => {
+    const { runner, statements } = createQueryRunner();
+
+    const sql = await dumpDatabaseToSql(runner, {
+      source: "local",
+      dialect: "sqlite",
+      tables: ["post"],
+      pageSize: 5,
+      selectSqlByTable: {
+        post: `SELECT * FROM "post" WHERE "site_id" = 'site' ORDER BY "id"\n`,
+      },
+    });
+
+    expect(
+      statements.filter((statement) => statement.includes('FROM "post"')),
+    ).toEqual([
+      `SELECT * FROM "post" WHERE "site_id" = 'site' ORDER BY "id" LIMIT 5 OFFSET 0`,
+      `SELECT * FROM "post" WHERE "site_id" = 'site' ORDER BY "id" LIMIT 5 OFFSET 5`,
+    ]);
+    expect(sql.match(/INSERT INTO "post"/g)).toHaveLength(7);
+  });
+
+  it("reads a table in one query without a page size", async () => {
+    const { runner, statements } = createQueryRunner();
+
+    await dumpDatabaseToSql(runner, {
+      source: "node",
+      dialect: "sqlite",
+      tables: ["post"],
+    });
+
+    expect(
+      statements.filter((statement) => statement.includes('FROM "post"')),
+    ).toEqual(['SELECT * FROM "post"']);
+  });
+});
+
+describe("describeWranglerFailure", () => {
+  it("names the buffer overflow instead of echoing the rows", () => {
+    const error = Object.assign(new Error("spawnSync node ENOBUFS"), {
+      code: "ENOBUFS",
+      stdout: '[{"results":[' + '{"id":"pst_x","body":"…"},'.repeat(50_000),
+      stderr: "",
+    });
+
+    const message = describeWranglerFailure(
+      ["d1", "execute", "DB", "--local", "--json"],
+      error,
+    );
+
+    expect(message).toBe(
+      `\`wrangler d1 execute DB\` printed more than ${WRANGLER_MAX_BUFFER} bytes, the most the CLI buffers.`,
+    );
+  });
+
+  it("keeps a long failure's stdout to an excerpt", () => {
+    const message = describeWranglerFailure(["d1", "execute", "DB"], {
+      name: "Error",
+      message: "Command failed",
+      stdout: "x".repeat(10_000),
+      stderr: "",
+    } as Error & { stdout: string; stderr: string });
+
+    expect(message.length).toBeLessThan(2_200);
+    expect(message).toContain("(10000 characters)");
+  });
+});
+
+describe("snapshot post order", () => {
+  it("puts every post after its root and the post it replies to", () => {
+    const rows = [
+      { id: "reply-2", thread_id: "root", reply_to_id: "reply-1" },
+      { id: "reply-1", thread_id: "root", reply_to_id: "root" },
+      { id: "other", thread_id: "other", reply_to_id: null },
+      { id: "root", thread_id: "root", reply_to_id: null },
+    ];
+
+    expect(orderSnapshotPostRows(rows).map((row) => row.id)).toEqual([
+      "root",
+      "reply-1",
+      "reply-2",
+      "other",
+    ]);
+  });
+
+  it("keeps the dump order when parents already come first", () => {
+    const rows = [
+      { id: "a", thread_id: "a", reply_to_id: null },
+      { id: "b", thread_id: "a", reply_to_id: "a" },
+      { id: "c", thread_id: "c", reply_to_id: null },
+    ];
+
+    expect(orderSnapshotPostRows(rows)).toEqual(rows);
+  });
+
+  it("applies a table's row order to the dump", async () => {
+    const { runner } = createQueryRunner();
+
+    const sql = await dumpDatabaseToSql(runner, {
+      source: "node",
+      dialect: "sqlite",
+      tables: ["post"],
+      orderRowsByTable: {
+        post: (rows: Record<string, unknown>[]) => [...rows].reverse(),
+      },
+    });
+
+    expect(sql.indexOf("'pst_6'")).toBeLessThan(sql.indexOf("'pst_0'"));
+  });
+});

package/src/__tests__/stylesheet-audience.test.ts

@@ -0,0 +1,159 @@
+import { describe, expect, it } from "vitest";
+import {
+  readAuthorCss,
+  readComponentCss,
+  readReaderCss,
+} from "./helpers/component-css.js";
+
+/**
+ * `client.css` is what a signed-out visitor waits on before the page paints,
+ * and `styles/ui.css` plus `styles/components.css` are the hand-written half
+ * of it. Author-only component CSS belongs in `styles/ui-author.css` and
+ * `styles/components-author.css`, which `BaseLayout` links only on
+ * authenticated pages.
+ *
+ * Class families that only ever appear in authenticated markup. The editor's
+ * `.tiptap-*` chrome is here too, minus the names TipTap also writes into
+ * published post HTML — readers see those.
+ */
+const AUTHOR_ONLY = [
+  "compose",
+  "command",
+  "settings",
+  "picker",
+  "confirm",
+  "draft",
+  "theme-preview",
+  // The floating compose button on phones, and the page modifier that keeps
+  // room for it. Reader layout renders both, but only for a signed-in author.
+  "site-mobile-compose",
+  "site-page-mobile-compose-enabled",
+  // From `components.css`: the config editor, the navigation manager, the
+  // custom URL manager, the dash chrome and the form skeletons. `.nav-*` here
+  // is `jant-nav-manager`, not the site header — that is `.site-header-nav`.
+  // `.collection-picker-*` is spelled out because plain `.collection-*` is a
+  // reader family (the collection pages).
+  "config",
+  "nav",
+  "custom",
+  "dash",
+  "skel",
+  "collection-picker",
+];
+
+/** TipTap class names that land in reader-rendered post HTML. */
+const READER_TIPTAP = [
+  "tiptap-table",
+  "tiptap-html-block",
+  "tiptap-more-break",
+  "tiptap-embed-figure",
+  "tiptap-embed-frame",
+  "tiptap-embed-fallback",
+  "tiptap-footnote-reference",
+  "tiptap-footnote-definition",
+];
+
+/**
+ * `.compose-thread-layout` shares the compose rail's marker vocabulary with
+ * the reading rail's `.thread-group` in one declaration, so that the two
+ * cannot drift apart. That single grouped selector is the documented
+ * exception; see the comment on the rule in `styles/ui.css`.
+ */
+const READER_SHEET_EXCEPTIONS = [".compose-thread-layout"];
+
+/** Every class named in a selector, ignoring declaration bodies. */
+function selectorClasses(css: string): string[] {
+  const found: string[] = [];
+  // Selectors are what precedes a `{` that opens a block; declarations end in
+  // `;`, so anything after the last `;` or `}` is the selector text.
+  for (const chunk of css.split("{")) {
+    const selector = chunk.slice(
+      Math.max(chunk.lastIndexOf(";"), chunk.lastIndexOf("}")) + 1,
+    );
+    const withoutComments = selector.replace(/\/\*[\s\S]*?\*\//g, " ");
+    for (const match of withoutComments.matchAll(
+      /\.(-?[A-Za-z_][A-Za-z0-9_-]*)/g,
+    )) {
+      found.push(match[1]!);
+    }
+  }
+  return found;
+}
+
+describe("stylesheet audience", () => {
+  it("keeps author-only component CSS out of the reader stylesheet", () => {
+    const css = readReaderCss();
+    const exceptions = new Set(
+      READER_SHEET_EXCEPTIONS.map((name) => name.replace(/^\./, "")),
+    );
+
+    const leaked = [
+      ...new Set(
+        selectorClasses(css).filter(
+          (name) =>
+            !exceptions.has(name) &&
+            AUTHOR_ONLY.some(
+              (family) => name === family || name.startsWith(`${family}-`),
+            ),
+        ),
+      ),
+    ].sort();
+
+    expect(leaked).toEqual([]);
+  });
+
+  it("keeps the editor chrome out of the reader stylesheet", () => {
+    const readerTiptap = new Set(READER_TIPTAP);
+    const leaked = [
+      ...new Set(
+        selectorClasses(readReaderCss()).filter(
+          (name) =>
+            (name === "tiptap" || name.startsWith("tiptap-")) &&
+            !readerTiptap.has(name),
+        ),
+      ),
+    ].sort();
+
+    expect(leaked).toEqual([]);
+  });
+
+  it("still styles the TipTap output a published post carries", () => {
+    // `lib/embed-render.ts` and `lib/markdown-manager.ts` write these into post
+    // HTML, and they are the ones with rules of their own — a reader holding
+    // only `client.css` has to be able to style them. The rest of
+    // READER_TIPTAP reaches published posts too but is styled by element
+    // through `.prose`, so there is no rule here to keep.
+    const css = readReaderCss();
+    for (const name of [
+      "tiptap-embed-figure",
+      "tiptap-embed-frame",
+      "tiptap-embed-fallback",
+      "tiptap-more-break",
+    ]) {
+      expect(selectorClasses(css)).toContain(name);
+    }
+  });
+
+  it("moved real weight, not a handful of rules", () => {
+    // The split is only worth its complexity while the author half is
+    // substantial. If it ever shrinks to a rounding error, fold it back in.
+    expect(readAuthorCss().length).toBeGreaterThan(readReaderCss().length / 2);
+  });
+
+  it("keeps the author half of components.css out of the reader sheet", () => {
+    // `preset.css` imports `components.css` on every page, so the settings
+    // pages and the config editor must not be left in it.
+    const author = readAuthorCss();
+    expect(author).toContain(".settings-root");
+    expect(author).toContain(".config-editor-page");
+  });
+
+  it("leaves the reader-side families of components.css in place", () => {
+    // Verified against every `class=` usage in the tree: `BaseLayout` renders
+    // the toast container on every page, and `.page-intro-*` is the header of
+    // the archive and collections pages, both public.
+    const reader = readReaderCss();
+    expect(reader).toContain(".toast-container");
+    expect(reader).toContain(".page-intro");
+  });
+});