@opensaas/stack-core 0.34.0 → 0.35.0

package/tests/bare-read-scalars.test.ts

@@ -0,0 +1,147 @@
+import { describe, it, expect, vi } from 'vitest'
+import { getContext } from '../src/context/index.js'
+import { config, list } from '../src/config/index.js'
+import { text, relationship, virtual } from '../src/fields/index.js'
+
+/**
+ * Regression coverage for issue #848 / ADR-0024: a `context.db` read with no
+ * `include` (and no fragment `query`) used to auto-include every readable
+ * relationship of the list, recursing to `READ_INCLUDE_MAX_DEPTH` and
+ * evaluating every related list's operation-level `query` access along the
+ * way. It now returns the row's own columns plus its virtual fields — nothing
+ * more — matching Prisma's own semantics for a bare read. Relations are
+ * fetched only when a caller names them via `include` (covered, unmodified,
+ * by the #566/#830 regression suites in `context.test.ts`).
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function createMockPrisma(): any {
+  return {
+    author: {
+      findFirst: vi.fn(),
+      findMany: vi.fn(),
+      create: vi.fn(),
+      update: vi.fn(),
+      delete: vi.fn(),
+      count: vi.fn(),
+    },
+    post: {
+      findFirst: vi.fn(),
+      findMany: vi.fn(),
+      create: vi.fn(),
+      update: vi.fn(),
+      delete: vi.fn(),
+      count: vi.fn(),
+    },
+  }
+}
+
+function buildTestConfig(authorQuerySpy: ReturnType<typeof vi.fn>) {
+  return config({
+    db: { provider: 'postgresql', url: 'postgresql://localhost:5432/test' },
+    lists: {
+      Author: list({
+        fields: {
+          name: text(),
+        },
+        access: { operation: { query: authorQuerySpy } },
+      }),
+      Post: list({
+        fields: {
+          title: text(),
+          // List-only ref keeps the schema minimal — the relation still owns
+          // an `authorId` foreign-key column, which is what matters here.
+          author: relationship({ ref: 'Author' }),
+          shout: virtual({
+            type: 'string',
+            hooks: {
+              resolveOutput: ({ item }) => `${(item as { title?: string }).title}!`,
+            },
+          }),
+        },
+        access: { operation: { query: () => true } },
+      }),
+    },
+  })
+}
+
+describe('a bare read fetches scalars, not relations (#848, ADR-0024)', () => {
+  it('findUnique with no include sends no include to the ORM and evaluates no related query access', async () => {
+    const authorQuerySpy = vi.fn(() => true)
+    const testConfig = await buildTestConfig(authorQuerySpy)
+    const mockPrisma = createMockPrisma()
+    mockPrisma.post.findFirst.mockResolvedValue({ id: '1', title: 'Hello', authorId: 'a1' })
+
+    const context = getContext(testConfig, mockPrisma, null)
+    const result = await context.db.post.findUnique({ where: { id: '1' } })
+
+    expect(mockPrisma.post.findFirst).toHaveBeenCalledWith({
+      where: { id: '1' },
+      include: undefined,
+    })
+    // Related list's operation-level `query` access is never invoked — a bare
+    // read never even considers whether the relation is fetchable.
+    expect(authorQuerySpy).not.toHaveBeenCalled()
+
+    // Own columns (including the FK column) and the computed virtual field
+    // are present; the relation key is absent entirely.
+    expect(result).toEqual({ id: '1', title: 'Hello', authorId: 'a1', shout: 'Hello!' })
+    expect(result).not.toHaveProperty('author')
+  })
+
+  it('findMany with no include sends no include to the ORM and evaluates no related query access', async () => {
+    const authorQuerySpy = vi.fn(() => true)
+    const testConfig = await buildTestConfig(authorQuerySpy)
+    const mockPrisma = createMockPrisma()
+    mockPrisma.post.findMany.mockResolvedValue([{ id: '1', title: 'Hello', authorId: 'a1' }])
+
+    const context = getContext(testConfig, mockPrisma, null)
+    const result = await context.db.post.findMany({})
+
+    expect(mockPrisma.post.findMany).toHaveBeenCalledWith(
+      expect.objectContaining({ include: undefined }),
+    )
+    expect(authorQuerySpy).not.toHaveBeenCalled()
+
+    expect(result).toEqual([{ id: '1', title: 'Hello', authorId: 'a1', shout: 'Hello!' }])
+    expect(result[0]).not.toHaveProperty('author')
+  })
+
+  it('a caller-supplied include still evaluates the related query access (unchanged)', async () => {
+    const authorQuerySpy = vi.fn(() => true)
+    const testConfig = await buildTestConfig(authorQuerySpy)
+    const mockPrisma = createMockPrisma()
+    mockPrisma.post.findFirst.mockResolvedValue({
+      id: '1',
+      title: 'Hello',
+      authorId: 'a1',
+      author: { id: 'a1', name: 'Ann' },
+    })
+
+    const context = getContext(testConfig, mockPrisma, null)
+    const result = await context.db.post.findUnique({
+      where: { id: '1' },
+      include: { author: true },
+    })
+
+    expect(authorQuerySpy).toHaveBeenCalled()
+    expect(result?.author).toEqual({ id: 'a1', name: 'Ann' })
+  })
+
+  it('sudo bare read also sends no include (behaviour already matched Prisma; unaffected by this change)', async () => {
+    const authorQuerySpy = vi.fn(() => true)
+    const testConfig = await buildTestConfig(authorQuerySpy)
+    const mockPrisma = createMockPrisma()
+    mockPrisma.post.findFirst.mockResolvedValue({ id: '1', title: 'Hello', authorId: 'a1' })
+
+    const context = getContext(testConfig, mockPrisma, null).sudo()
+    const result = await context.db.post.findUnique({ where: { id: '1' } })
+
+    expect(mockPrisma.post.findFirst).toHaveBeenCalledWith({
+      where: { id: '1' },
+      include: undefined,
+    })
+    expect(authorQuerySpy).not.toHaveBeenCalled()
+    expect(result).toEqual({ id: '1', title: 'Hello', authorId: 'a1', shout: 'Hello!' })
+  })
+})

package/tests/nested-access-and-hooks.test.ts

@@ -397,8 +397,12 @@ describe('Nested Operations - Access Control and Hooks', () => {
 
       const context = getContext(await testConfig, mockPrisma, null)
 
+      // A caller-supplied `include` is required to fetch `posts` at all — a
+      // bare read returns scalars only (ADR-0024) — so name it explicitly to
+      // exercise the per-relation access `where` merge.
       await context.db.user.findUnique({
         where: { id: '1' },
+        include: { posts: true },
       })
 
       // Verify findFirst was called with access filter
@@ -469,8 +473,11 @@ describe('Nested Operations - Access Control and Hooks', () => {
 
       const context = getContext(await testConfig, mockPrisma, null)
 
+      // `author` must be named explicitly — a bare read returns scalars only
+      // (ADR-0024).
       const result = await context.db.post.findUnique({
         where: { id: '1' },
+        include: { author: true },
       })
 
       // Email should be filtered out
@@ -522,8 +529,11 @@ describe('Nested Operations - Access Control and Hooks', () => {
 
       const context = getContext(await testConfig, mockPrisma, null)
 
+      // `author` must be named explicitly to exercise the access-denied drop —
+      // a bare read never requests it at all (ADR-0024).
       await context.db.post.findUnique({
         where: { id: '1' },
+        include: { author: true },
       })
 
       // Verify include does NOT include author (access denied)

package/tests/resolve-chain.test.ts

@@ -136,9 +136,12 @@ describe('resolve chain — cycle guard terminates hook-issued reads (#844)', ()
     )
   })
 
-  it("reproduces the reporter's 3-list cyclic schema (User → Account → Student) within a bounded query budget", async () => {
+  it("no longer reproduces the reporter's 3-list cyclic schema (User → Account → Student) on a bare hook-issued read (#848, ADR-0024)", async () => {
     // Sketch matches the issue's minimal reproduction: User.name reads
-    // Account, whose Student rows' own virtual field reads Account again.
+    // Account, whose Student rows' own virtual field reads Account again. The
+    // hook's read is BARE (no `include`), so under ADR-0024 it fetches
+    // Account's own columns only — `students` is never fetched, the walk into
+    // `Student.label` never happens, and the cycle cannot form.
     const config: OpenSaasConfig = {
       db: { provider: 'postgresql', url: 'postgresql://localhost:5432/test' },
       lists: {
@@ -191,33 +194,42 @@ describe('resolve chain — cycle guard terminates hook-issued reads (#844)', ()
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const prisma: any = { user: makeModel(), account: makeModel(), student: makeModel() }
     prisma.user.findMany.mockResolvedValue([{ id: 'u1' }])
-    // Account rows returned to a hook-issued read embed their (row-scoped,
-    // one-level) relations directly — deliberately WITHOUT `user`, so the
-    // walk goes through `students` → `Student.label`, matching the trace in
-    // the issue rather than short-circuiting through the `user` back-edge.
-    prisma.account.findMany.mockResolvedValue([
-      { id: 'a1', firstName: 'Ann', students: [{ id: 's1', accountId: 'a1' }] },
-    ])
+    // Mirrors real Prisma semantics: a relation key is only present on the
+    // returned row when the caller actually asked for it via `include`. The
+    // hook's read never does, so `students` (and `user`) never appear here —
+    // that is the mechanism that breaks the cycle under ADR-0024.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    prisma.account.findMany.mockImplementation((args: any = {}) => {
+      const row: Record<string, unknown> = { id: 'a1', firstName: 'Ann' }
+      if (args.include?.students) row.students = [{ id: 's1', accountId: 'a1' }]
+      if (args.include?.user) row.user = { id: 'u1' }
+      return Promise.resolve([row])
+    })
     // `context.db.<list>.findUnique` is implemented via the Prisma model's
     // `findFirst` (see `createFindUnique` in `context/index.ts`), not its
     // `findUnique` — mock the method actually called.
-    prisma.account.findFirst.mockResolvedValue({
-      id: 'a1',
-      firstName: 'Ann',
-      students: [{ id: 's1', accountId: 'a1' }],
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    prisma.account.findFirst.mockImplementation((args: any = {}) => {
+      const row: Record<string, unknown> = { id: 'a1', firstName: 'Ann' }
+      if (args.include?.students) row.students = [{ id: 's1', accountId: 'a1' }]
+      if (args.include?.user) row.user = { id: 'u1' }
+      return Promise.resolve(row)
     })
 
     const context = await getContext(config, prisma, null)
 
-    // Must settle (not hang), and must not have driven an unbounded number of
-    // queries before doing so — this is the actual OOM mechanism from #844.
-    await expect(context.db.user.findMany({})).rejects.toThrow(ResolveOutputCycleError)
+    // Must settle (not hang or throw) — the bare hook-issued read never
+    // fetches `students`, so `Student.label` never fires and there is no
+    // cycle to detect.
+    const result = await context.db.user.findMany({})
+    expect(result).toEqual([{ id: 'u1', name: 'Ann' }])
 
+    // Only the two reads the hook actually issues — no unbounded recursion.
     const totalCalls =
       prisma.user.findMany.mock.calls.length +
       prisma.account.findMany.mock.calls.length +
       prisma.account.findFirst.mock.calls.length
-    expect(totalCalls).toBeLessThan(20)
+    expect(totalCalls).toBe(2)
   })
 })
 
@@ -319,7 +331,7 @@ describe('resolve chain — concurrent hook invocations are isolated (#844)', ()
     expect(observedLengths.sort()).toEqual([1, 1, 1])
   })
 
-  it('an unrelated top-level read in flight alongside a hook still gets its full nested auto-include', async () => {
+  it('an unrelated top-level read in flight alongside a hook still gets its full explicit include scoped', async () => {
     let releaseSlowHook: () => void = () => {}
 
     const config: OpenSaasConfig = {
@@ -377,16 +389,21 @@ describe('resolve chain — concurrent hook invocations are isolated (#844)', ()
     await new Promise((resolve) => setTimeout(resolve, 0))
 
     // While the slow hook is still in flight, issue a plain top-level read
-    // that has nothing to do with it.
-    const fastPromise = context.db.fast.findMany({})
+    // that has nothing to do with it. A bare read fetches scalars only
+    // (ADR-0024), so name `child` explicitly — a caller include naming a
+    // relation BARE (`true`, no nested include of its own) still picks up the
+    // access-controlled include for whatever lies beneath it.
+    const fastPromise = context.db.fast.findMany({ include: { child: true } })
 
     await fastPromise
     releaseSlowHook()
     await slowPromise
 
-    // The unrelated read's auto-include must still descend two levels deep
-    // (child → grandchild), not collapse to a bare `{ child: true }` because
-    // it happened to run while a totally different read's hook was active.
+    // The unrelated read's access-controlled scoping must still descend two
+    // levels deep (child → grandchild), not collapse to a bare `{ child: true }`
+    // because it happened to run while a totally different read's hook was
+    // active — `insideResolveOutput` must stay scoped to the hook's OWN
+    // derived context, never leak into a concurrently-running, unrelated one.
     expect(prisma.fast.findMany.mock.calls[0][0].include).toEqual({
       child: { include: { grandchild: true } },
     })

package/tests/singleton.test.ts

@@ -205,6 +205,89 @@ describe('Singleton Lists', () => {
     })
   })
 
+  describe('get() with a caller include (#848, ADR-0024)', () => {
+    // A singleton read gains the same caller-`include` handling as findUnique
+    // and findMany: bare fetches scalars only, and a caller include is merged
+    // with the access-controlled include (row-scoped per relation).
+    it("a bare get() sends no include and does not evaluate the related list's query access", async () => {
+      const homeAuthorQuerySpy = vi.fn(() => true)
+      const relConfig: OpenSaasConfig = {
+        db: { provider: 'postgresql', url: 'postgresql://localhost:5432/test' },
+        lists: {
+          HomePage: {
+            fields: {
+              title: { type: 'text' },
+              featuredAuthor: { type: 'relationship', ref: 'Author' },
+            },
+            access: { operation: { query: () => true, create: () => true } },
+            isSingleton: true,
+          },
+          Author: {
+            fields: { name: { type: 'text' } },
+            access: { operation: { query: homeAuthorQuerySpy } },
+          },
+        },
+      }
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const relPrisma: any = {
+        homePage: { findFirst: vi.fn(), create: vi.fn(), count: vi.fn() },
+        author: { findFirst: vi.fn(), findMany: vi.fn() },
+      }
+      relPrisma.homePage.findFirst.mockResolvedValue({
+        id: 1,
+        title: 'Home',
+        featuredAuthorId: 'a1',
+      })
+
+      const context = getContext(relConfig, relPrisma, null)
+      const result = await context.db.homePage.get()
+
+      expect(relPrisma.homePage.findFirst).toHaveBeenCalledWith({ where: {}, include: undefined })
+      expect(homeAuthorQuerySpy).not.toHaveBeenCalled()
+      expect(result).toEqual({ id: 1, title: 'Home', featuredAuthorId: 'a1' })
+      expect(result).not.toHaveProperty('featuredAuthor')
+    })
+
+    it('a caller include on get() is merged with the access-controlled include, row-scoped like any other read', async () => {
+      const homeAuthorQuerySpy = vi.fn(() => ({ published: { equals: true } }))
+      const relConfig: OpenSaasConfig = {
+        db: { provider: 'postgresql', url: 'postgresql://localhost:5432/test' },
+        lists: {
+          HomePage: {
+            fields: {
+              title: { type: 'text' },
+              featuredAuthor: { type: 'relationship', ref: 'Author' },
+            },
+            access: { operation: { query: () => true, create: () => true } },
+            isSingleton: true,
+          },
+          Author: {
+            fields: { name: { type: 'text' } },
+            access: { operation: { query: homeAuthorQuerySpy } },
+          },
+        },
+      }
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const relPrisma: any = {
+        homePage: { findFirst: vi.fn(), create: vi.fn(), count: vi.fn() },
+        author: { findFirst: vi.fn(), findMany: vi.fn() },
+      }
+      relPrisma.homePage.findFirst.mockResolvedValue({
+        id: 1,
+        title: 'Home',
+        featuredAuthorId: 'a1',
+        featuredAuthor: { id: 'a1', name: 'Ann' },
+      })
+
+      const context = getContext(relConfig, relPrisma, null)
+      const result = await context.db.homePage.get({ include: { featuredAuthor: true } })
+
+      const call = relPrisma.homePage.findFirst.mock.calls[0][0]
+      expect(call.include.featuredAuthor).toEqual({ where: { published: { equals: true } } })
+      expect(result?.featuredAuthor).toEqual({ id: 'a1', name: 'Ann' })
+    })
+  })
+
   describe('delete operation', () => {
     it('should block delete on singleton lists', async () => {
       mockPrisma.settings.findUnique.mockResolvedValue({