@supatype/cli 0.2.1 → 0.3.0

package/tests/model-cache-declaration.test.ts

@@ -0,0 +1,229 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { afterEach, describe, expect, it } from "vitest"
+import { extractSchemaAstFromTypes } from "../src/type-extractor.js"
+
+// `cache` is declared on the model because two of its four settings cannot be checked anywhere
+// else. `public` is a data-leak switch whose safety depends on `access.read`, which is right there
+// in the same object; `rows` depends on there being a primary key. A Studio checkbox can see
+// neither, which is the argument for the declaration existing at all (plan §13.3).
+
+const dirs: string[] = []
+
+afterEach(() => {
+  for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true })
+})
+
+function extract(body: string): ReturnType<typeof extractSchemaAstFromTypes> {
+  const dir = mkdtempSync(join(tmpdir(), "supatype-cache-"))
+  dirs.push(dir)
+  const schemaPath = join(dir, "schema.ts")
+  writeFileSync(
+    schemaPath,
+    `
+import type {
+  AuthUid, DateTime, Eq, LoggedIn, Lte, Model, Now, Optional, Owner, Public, Role, UUID,
+} from "@supatype/types"
+
+${body}
+`,
+    "utf8",
+  )
+  return extractSchemaAstFromTypes(schemaPath, dir)
+}
+
+const cacheOf = (ast: ReturnType<typeof extractSchemaAstFromTypes>): unknown =>
+  ast?.models[0]?.annotations.platform.cache
+
+describe("the declaration itself", () => {
+  it("carries all four settings through", () => {
+    const ast = extract(`
+export type Post = Model<{
+  id: UUID
+  title: Slug
+}, {
+  access: { read: Public }
+  cache: { enabled: true; maxTtl: 60; public: true; rows: true }
+}>`)
+    expect(cacheOf(ast)).toEqual({ enabled: true, maxTtl: 60, public: true, rows: true })
+  })
+
+  it("is absent when the model declares none, which is what makes it uncacheable", () => {
+    const ast = extract(`
+export type Post = Model<{ id: UUID; title: Slug }, { access: { read: Public } }>`)
+    expect(cacheOf(ast)).toBeUndefined()
+  })
+
+  it("treats an empty block as no declaration rather than an empty ceiling", () => {
+    // "Declared but permitting nothing" reads the same as saying nothing, and an empty entry in
+    // every manifest is noise a reader has to interpret.
+    const ast = extract(`
+export type Post = Model<{ id: UUID; title: Slug }, { access: { read: Public }; cache: {} }>`)
+    expect(cacheOf(ast)).toBeUndefined()
+  })
+
+  it("keeps an explicit false, because it is a hard opt-out and not a default", () => {
+    const ast = extract(`
+export type Post = Model<{ id: UUID; title: Slug }, {
+  access: { read: Public }
+  cache: { enabled: false }
+}>`)
+    expect(cacheOf(ast)).toEqual({ enabled: false })
+  })
+})
+
+describe("public caching on a caller-varying table", () => {
+  it("is refused, naming the model", () => {
+    // The check §13.3 calls worth the feature on its own. Nothing else in the system can see both
+    // the cache setting and the read rule at once.
+    expect(() =>
+      extract(`
+export type Post = Model<{ id: UUID; user_id: UUID; title: Slug }, {
+  access: { read: Owner<"user_id"> }
+  cache: { enabled: true; public: true }
+}>`),
+    ).toThrow(/cache\.public.*varies by caller|varies by caller.*cache\.public/s)
+  })
+
+  it("is refused for LoggedIn, which still separates members from strangers", () => {
+    expect(() =>
+      extract(`
+export type Post = Model<{ id: UUID; title: Slug }, {
+  access: { read: LoggedIn }
+  cache: { enabled: true; public: true }
+}>`),
+    ).toThrow(/cache\.public/)
+  })
+
+  it("is refused when the rule compares a column to the caller", () => {
+    expect(() =>
+      extract(`
+export type Post = Model<{ id: UUID; user_id: UUID; title: Slug }, {
+  access: { read: Eq<"user_id", AuthUid> }
+  cache: { enabled: true; public: true }
+}>`),
+    ).toThrow(/cache\.public/)
+  })
+
+  it("suggests the fix rather than only refusing", () => {
+    let message = ""
+    try {
+      extract(`
+export type Post = Model<{ id: UUID; user_id: UUID; title: Slug }, {
+  access: { read: Owner<"user_id"> }
+  cache: { enabled: true; public: true }
+}>`)
+    } catch (e) {
+      message = e instanceof Error ? e.message : String(e)
+    }
+    expect(message).toContain("enabled: true")
+    expect(message).toContain("published_at")
+  })
+})
+
+describe("public caching where sharing is the point", () => {
+  it("is allowed on a Public read rule", () => {
+    const ast = extract(`
+export type Post = Model<{ id: UUID; title: Slug }, {
+  access: { read: Public }
+  cache: { enabled: true; public: true }
+}>`)
+    expect(cacheOf(ast)).toEqual({ enabled: true, public: true })
+  })
+
+  it("is allowed on a rule that varies by row and by time but not by caller", () => {
+    // Refusing this would remove the case public caching exists to serve, so it is asserted from
+    // the permitting side too — a classifier stuck on "identity-dependent" would pass every test
+    // above and fail this one.
+    const ast = extract(`
+export type Post = Model<{ id: UUID; published_at: Optional<DateTime>; title: Slug }, {
+  access: { read: Lte<"published_at", Now> }
+  cache: { enabled: true; public: true }
+}>`)
+    expect(cacheOf(ast)).toEqual({ enabled: true, public: true })
+  })
+
+  it("is allowed when public is not asked for, whatever the read rule", () => {
+    const ast = extract(`
+export type Post = Model<{ id: UUID; user_id: UUID; title: Slug }, {
+  access: { read: Owner<"user_id"> }
+  cache: { enabled: true }
+}>`)
+    expect(cacheOf(ast)).toEqual({ enabled: true })
+  })
+})
+
+describe("the row cache needs something to key on", () => {
+  it("refuses rows on a model with no primary key", () => {
+    expect(() =>
+      extract(`
+export type Reading = Model<{ sensor: Slug; value: Slug }, {
+  access: { read: Public }
+  cache: { enabled: true; rows: true }
+}>`),
+    ).toThrow(/cache\.rows.*primary key|primary key.*cache\.rows/s)
+  })
+
+  it("allows rows where there is a primary key", () => {
+    const ast = extract(`
+export type Post = Model<{ id: UUID; title: Slug }, {
+  access: { read: Public }
+  cache: { enabled: true; rows: true }
+}>`)
+    expect(cacheOf(ast)).toEqual({ enabled: true, rows: true })
+  })
+
+  it("says what to do instead of only refusing", () => {
+    let message = ""
+    try {
+      extract(`
+export type Reading = Model<{ sensor: Slug; value: Slug }, {
+  access: { read: Public }
+  cache: { rows: true }
+}>`)
+    } catch (e) {
+      message = e instanceof Error ? e.message : String(e)
+    }
+    expect(message).toContain("response cache")
+  })
+
+  it("does not complain about a missing key when rows was not asked for", () => {
+    const ast = extract(`
+export type Reading = Model<{ sensor: Slug; value: Slug }, {
+  access: { read: Public }
+  cache: { enabled: true }
+}>`)
+    expect(cacheOf(ast)).toEqual({ enabled: true })
+  })
+})
+
+describe("the TTL bound, enforced where the number was written", () => {
+  const withTtl = (ttl: string) => () =>
+    extract(`
+export type Post = Model<{
+  id: UUID
+  title: Slug
+}, {
+  access: { read: Public }
+  cache: { enabled: true; maxTtl: ${ttl} }
+}>`)
+
+  it("refuses a cap the admin API would refuse", () => {
+    // 86400 is the bound `PATCH /admin/v1/config/rest` enforces on the project-wide TTL, and a
+    // declared cap is the same quantity. Left to the server it arrives inside a manifest rather
+    // than a request, and nothing refuses a manifest.
+    expect(withTtl("90000")).toThrow(/between 0 and 86400 seconds/)
+    expect(withTtl("-1")).toThrow(/between 0 and 86400 seconds/)
+  })
+
+  it("refuses a fractional cap rather than rounding one", () => {
+    expect(withTtl("1.5")).toThrow(/whole number of seconds/)
+  })
+
+  it("accepts the bounds themselves", () => {
+    expect(withTtl("86400")).not.toThrow()
+    // Zero is the absence of a declared cap, not a cap of zero — both ends read it that way.
+    expect(withTtl("0")).not.toThrow()
+  })
+})

package/tests/model-cache-manifest.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from "vitest"
+import { manifestCache } from "../src/model-cache.js"
+
+// The declaration reaches the server on the route manifest, keyed by table, exactly as `hooks`
+// does — and for the same reason. The schema engine re-serialises its own parsed struct when it
+// writes `ast_snapshot`, and its platform annotations know only `access` and `searchFields`, so a
+// `cache` key left to ride the AST is dropped in silence somewhere between push and the server.
+
+function ast(models: unknown[]): unknown {
+  return { models }
+}
+
+function model(table: string, cache?: unknown): unknown {
+  return {
+    name: table,
+    annotations: { db: { tableName: table }, platform: { ...(cache !== undefined && { cache }) } },
+  }
+}
+
+describe("what reaches the manifest", () => {
+  it("keys by table, not by model name", () => {
+    // The model name never reaches the wire; a REST path carries the table.
+    const out = manifestCache(
+      ast([
+        {
+          name: "BlogPost",
+          annotations: { db: { tableName: "blog_posts" }, platform: { cache: { enabled: true } } },
+        },
+      ]),
+    )
+    expect(out).toEqual({ blog_posts: { enabled: true } })
+  })
+
+  it("carries all four settings", () => {
+    const out = manifestCache(ast([model("posts", { enabled: true, maxTtl: 60, public: true, rows: true })]))
+    expect(out).toEqual({ posts: { enabled: true, maxTtl: 60, public: true, rows: true } })
+  })
+
+  it("omits a model that declared nothing, rather than writing an empty entry", () => {
+    // Load-bearing: the declaration is a ceiling, so absence means nothing may cache this table.
+    // An empty entry would say "declared, permitting nothing" — the same outcome by a route that
+    // looks like a bug.
+    expect(manifestCache(ast([model("posts")]))).toEqual({})
+  })
+
+  it("keeps an explicit false, which is a hard opt-out and not silence", () => {
+    expect(manifestCache(ast([model("posts", { enabled: false })]))).toEqual({
+      posts: { enabled: false },
+    })
+  })
+
+  it("carries maxTtl of zero, which means cache nothing rather than no opinion", () => {
+    expect(manifestCache(ast([model("posts", { maxTtl: 0 })]))).toEqual({ posts: { maxTtl: 0 } })
+  })
+})
+
+describe("what does not reach the manifest", () => {
+  it("drops keys the AST shape does not define", () => {
+    // Copied key by key on purpose. The manifest is a wire format another process parses, and
+    // widening it by accident is how the two ends stop agreeing what a field means.
+    const out = manifestCache(ast([model("posts", { enabled: true, somethingNew: true })]))
+    expect(out).toEqual({ posts: { enabled: true } })
+  })
+
+  it("drops a non-numeric or negative maxTtl rather than passing it on", () => {
+    expect(manifestCache(ast([model("a", { maxTtl: "60" })]))).toEqual({})
+    expect(manifestCache(ast([model("b", { maxTtl: -1 })]))).toEqual({})
+    expect(manifestCache(ast([model("c", { maxTtl: Number.NaN })]))).toEqual({})
+    expect(manifestCache(ast([model("d", { maxTtl: Number.POSITIVE_INFINITY })]))).toEqual({})
+  })
+
+  it("drops a non-boolean flag", () => {
+    expect(manifestCache(ast([model("posts", { enabled: "yes", rows: 1 })]))).toEqual({})
+  })
+
+  it("skips a model with no table name", () => {
+    expect(
+      manifestCache(ast([{ name: "X", annotations: { platform: { cache: { enabled: true } } } }])),
+    ).toEqual({})
+  })
+})
+
+describe("shapes that should not throw", () => {
+  it("survives an AST that is not one", () => {
+    expect(manifestCache(null)).toEqual({})
+    expect(manifestCache({})).toEqual({})
+    expect(manifestCache({ models: "not an array" })).toEqual({})
+  })
+
+  it("survives a model with no annotations at all", () => {
+    expect(manifestCache(ast([{ name: "X" }, null, 7]))).toEqual({})
+  })
+
+  it("survives a null cache", () => {
+    expect(
+      manifestCache(ast([{ annotations: { db: { tableName: "t" }, platform: { cache: null } } }])),
+    ).toEqual({})
+  })
+})

package/tests/model-hooks.test.ts

@@ -5,7 +5,9 @@ import { afterEach, describe, expect, it } from "vitest"
 import {
   DEFAULT_HOOK_TIMEOUT_MS,
   declaredHooks,
+  declaredValidators,
   manifestHooks,
+  manifestValidators,
   syncManifestHooks,
   hooksReport,
   validateModelHooks,
@@ -376,3 +378,56 @@ export type Post = Model<{ id: UUID }, { tableName: "posts" }>
     expect(report).toMatchObject({ missing: [], functionsDisabled: false, mapMissing: false })
   })
 })
+
+describe("a models array with something malformed in it", () => {
+  /*
+   * `x?.y` guards `x.y` being nullish, not `x` itself being null — so every one of these read
+   * `model.annotations` off a null and threw a TypeError out of `supatype push`. Not reachable
+   * from our own extractor, which never emits a null model; reachable from a hand-edited or
+   * third-party AST, and the failure is a stack trace rather than the entry being skipped.
+   *
+   * Asserted over all four readers at once, because the hole was copied between them: three
+   * already had it when the fourth was written, and only the fourth's own test found it.
+   */
+  const malformed = {
+    models: [
+      null,
+      undefined,
+      "posts",
+      42,
+      [],
+      { annotations: null },
+      { annotations: { db: null, platform: null } },
+      // One real model at the end, so a reader that bailed out of the loop rather than skipping
+      // the entry would be caught too.
+      {
+        name: "Post",
+        annotations: {
+          db: { tableName: "posts" },
+          platform: {
+            hooks: { beforeChange: { function: "moderate-post" } },
+            validate: { title: { function: "check-title" } },
+          },
+        },
+      },
+    ],
+  }
+
+  it("skips the bad entries rather than throwing", () => {
+    expect(() => declaredHooks(malformed)).not.toThrow()
+    expect(() => manifestHooks(malformed)).not.toThrow()
+    expect(() => declaredValidators(malformed)).not.toThrow()
+    expect(() => manifestValidators(malformed)).not.toThrow()
+  })
+
+  it("still reads the models that are well formed", () => {
+    expect(declaredHooks(malformed)).toEqual([
+      { model: "Post", event: "beforeChange", function: "moderate-post" },
+    ])
+    expect(manifestHooks(malformed)["posts"]?.["beforeChange"]?.function).toBe("moderate-post")
+    expect(declaredValidators(malformed)).toEqual([
+      { model: "Post", field: "title", function: "check-title" },
+    ])
+    expect(manifestValidators(malformed)["posts"]?.["title"]?.function).toBe("check-title")
+  })
+})

package/tests/model-versions.test.ts

@@ -0,0 +1,229 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { afterEach, describe, expect, it } from "vitest"
+import { extractSchemaAstFromTypes } from "../src/type-extractor.js"
+import {
+  DEFAULT_VERSIONS_KEPT,
+  modelsWithVersionsAndFieldRules,
+  resolveVersionsOptions,
+  schemaHasVersionedModels,
+  versionedModels,
+} from "../src/model-versioning.js"
+import { apiSchemaList, draftVisibilityRoles, previewLimits } from "../src/project-config.js"
+import type { SupatypeProjectConfig } from "../src/project-config.js"
+
+// A versioned model is opt-in and changes three things that are decided before any database exists:
+// the exposed schema list gains `draft`, the engine emits a versions table and a draft view, and a
+// model that also masks a column is refused. All three read `versions` out of the extracted AST, so
+// what the extractor puts there is the contract these tests pin.
+
+const dirs: string[] = []
+
+afterEach(() => {
+  for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true })
+})
+
+function extract(body: string): ReturnType<typeof extractSchemaAstFromTypes> {
+  const dir = mkdtempSync(join(tmpdir(), "supatype-versions-"))
+  dirs.push(dir)
+  const schemaPath = join(dir, "schema.ts")
+  writeFileSync(
+    schemaPath,
+    `
+import type {
+  Lte, Model, Now, Optional, Owner, Public, RichText, Role, Timestamp, UUID,
+} from "@supatype/types"
+
+${body}
+`,
+    "utf8",
+  )
+  return extractSchemaAstFromTypes(schemaPath, dir)
+}
+
+const POST = `
+export type Post = Model<{
+  id: UUID
+  title: string
+  body: RichText
+  published_at: Optional<Timestamp>
+}, {
+  tableName: "posts"
+  versions: { drafts: true; keep: 5 }
+  access: { read: Lte<"published_at", Now>; update: Role<"editor"> }
+}>
+`
+
+describe("the versions declaration", () => {
+  it("reaches the AST with its retention", () => {
+    const ast = extract(POST)
+    expect(ast?.models[0]?.options["versions"]).toEqual({ drafts: true, keep: 5 })
+  })
+
+  it("takes `true` as shorthand for drafts with the default retention", () => {
+    const ast = extract(`
+export type Note = Model<{ id: UUID; title: string }, { versions: true }>
+`)
+    expect(ast?.models[0]?.options["versions"]).toEqual({
+      drafts: true,
+      keep: DEFAULT_VERSIONS_KEPT,
+    })
+  })
+
+  it("keeps history without withholding writes when drafts are off", () => {
+    // The audit-trail case: every change recorded, nothing hidden from readers.
+    const ast = extract(`
+export type Ledger = Model<{ id: UUID; note: string }, { versions: { drafts: false } }>
+`)
+    expect(ast?.models[0]?.options["versions"]).toEqual({
+      drafts: false,
+      keep: DEFAULT_VERSIONS_KEPT,
+    })
+  })
+
+  it("is absent from a model that does not declare it", () => {
+    const ast = extract(`export type Plain = Model<{ id: UUID; title: string }>`)
+    expect(ast?.models[0]?.options["versions"]).toBeUndefined()
+    expect(schemaHasVersionedModels(ast)).toBe(false)
+  })
+
+  it("names the model and its table, which is what the generated relations are named after", () => {
+    const found = versionedModels(extract(POST))
+    expect(found).toEqual([
+      { name: "Post", tableName: "posts", options: { drafts: true, keep: 5 } },
+    ])
+  })
+})
+
+describe("versions alongside per-column rules", () => {
+  it("refuses the pair, naming the masked column", () => {
+    // A snapshot is opaque JSONB, so the masking that rewrites references to a real column cannot
+    // see inside it: the value would be readable in the versions table.
+    expect(() =>
+      extract(`
+export type Employee = Model<{ id: UUID; name: string; salary: number }, {
+  versions: true
+  access: { read: Public; fields: { salary: { read: Owner<"id"> } } }
+}>
+`),
+    ).toThrow(/`versions` and `access.fields` cannot both be declared[\s\S]*`salary`/)
+  })
+
+  it("allows a masked model and a versioned model in the same schema", () => {
+    // Per model, not per project. Under the view tier the managed schema comes off the exposed list
+    // but the API roles keep their privileges on the base tables, so a `security_invoker` view in an
+    // exposed schema reaches past the `api` layer: one model may not be both, a project may hold
+    // both.
+    const ast = extract(`
+export type Employee = Model<{ id: UUID; name: string; salary: number }, {
+  access: { read: Public; fields: { salary: { read: Owner<"id"> } } }
+}>
+
+export type Article = Model<{ id: UUID; title: string }, { versions: true }>
+`)
+    expect(ast?.models).toHaveLength(2)
+    expect(schemaHasVersionedModels(ast)).toBe(true)
+    expect(modelsWithVersionsAndFieldRules(ast)).toEqual([])
+  })
+})
+
+describe("resolveVersionsOptions", () => {
+  it("treats a retention of zero as unstated, since pruning to nothing deletes the open draft", () => {
+    expect(resolveVersionsOptions({ keep: 0 })).toEqual({
+      drafts: true,
+      keep: DEFAULT_VERSIONS_KEPT,
+    })
+  })
+
+  it("reads `false` and a non-object as no versioning at all", () => {
+    expect(resolveVersionsOptions(false)).toBeUndefined()
+    expect(resolveVersionsOptions(undefined)).toBeUndefined()
+    expect(resolveVersionsOptions("true")).toBeUndefined()
+  })
+})
+
+function project(overrides?: Partial<SupatypeProjectConfig>): SupatypeProjectConfig {
+  return {
+    projectName: "test",
+    database: { provider: "docker" },
+    ...overrides,
+  } as SupatypeProjectConfig
+}
+
+describe("the exposed schema list with drafts", () => {
+  it("adds `draft` behind the managed schema, never in front of it", () => {
+    // The first entry is PostgREST's default profile. `draft` leading would mean a client that named
+    // no profile read drafts by default, which inverts the whole feature.
+    expect(apiSchemaList(project(), { drafts: true })).toBe(
+      "public, draft, supatype, graphql_public, auth",
+    )
+  })
+
+  it("is unchanged when nothing is versioned", () => {
+    expect(apiSchemaList(project(), { drafts: false })).toBe(
+      "public, supatype, graphql_public, auth",
+    )
+  })
+
+  it("still lets an explicit api_schemas win, drafts or not", () => {
+    // Stating the list is the documented way to stop exposing a schema, and that has to hold for
+    // `draft` as much as for `supatype`.
+    const cfg = project({ schema: { api_schemas: ["public"] } })
+    expect(apiSchemaList(cfg, { drafts: true })).toBe("public")
+  })
+
+  it("serves drafts from the managed schema even under the view tier", () => {
+    // The draft views read the real tables, so tier 2 moving reads to `api` does not move them.
+    expect(apiSchemaList(project(), { tier: "views", drafts: true })).toBe(
+      "api, draft, supatype, graphql_public, auth",
+    )
+  })
+})
+
+describe("draft visibility", () => {
+  it("defaults to every Studio role, so seeing and acting line up", () => {
+    // Narrower than this put two decisions in conflict: whoever may update a record may draft it,
+    // so a role that can edit but cannot see drafts saves over a colleague's pending work.
+    expect(draftVisibilityRoles(project())).toEqual(["admin", "developer", "editor"])
+  })
+
+  it("honours an empty list as creators only", () => {
+    // Not a fallback case: narrowing to creators alone is a legitimate setting, so emptiness cannot
+    // mean "unstated".
+    expect(draftVisibilityRoles(project({ publishing: { draft_visibility: [] } }))).toEqual([])
+  })
+
+  it("drops a role no deployment understands", () => {
+    // A typo passed through to a policy would be a role nothing can hold, which reads as a working
+    // setting that grants nobody.
+    const cfg = project({
+      publishing: { draft_visibility: ["editor", "owner", "editor"] as never },
+    })
+    expect(draftVisibilityRoles(cfg)).toEqual(["editor"])
+  })
+})
+
+describe("preview limits", () => {
+  it("defaults to a short link, a week for a record and a day for a project", () => {
+    expect(previewLimits(project())).toEqual({
+      defaultTtl: 900,
+      maxRecordTtl: 604800,
+      maxProjectTtl: 86400,
+      allowProjectScope: true,
+    })
+  })
+
+  it("clamps a default lifetime above every ceiling it could be issued against", () => {
+    // Otherwise the same config mints links it then refuses to honour.
+    const cfg = project({
+      publishing: { preview: { default_ttl: 999999, max_record_ttl: 3600, max_project_ttl: 600 } },
+    })
+    expect(previewLimits(cfg).defaultTtl).toBe(3600)
+  })
+
+  it("ignores a nonsense lifetime rather than issuing a link that has already expired", () => {
+    const cfg = project({ publishing: { preview: { default_ttl: 0 } } })
+    expect(previewLimits(cfg).defaultTtl).toBe(900)
+  })
+})