refactor(files): trim restating comments and duplicate file-listing tests

Drops TSDoc that restated identifiers, tightens the list route's docs, and
removes the integration test that re-checked the cursor validation the
file-query unit test owns. The authorization test now asserts the forbidden
code and that the read member gets files, and the rollup test reads the root
stats once. The name-index plan test moves to the plan suite.

Author: waleedlatif1

apps/sim/app/api/workspaces/[id]/files/route.ts

@@ -27,7 +27,7 @@ import { readSortedCursor, writeSortedCursor } from '@/app/api/v2/lib/response'
 
 export const dynamic = 'force-dynamic'
 
-/** Every param that changes which files, in which order, a page walk returns. */
+/** The params besides the sort that change which files a page walk returns; the cursor is bound to them. */
 function fileCursorFilters(
   workspaceId: string,
   query: { scope: 'active' | 'archived'; folderId?: string | null }
@@ -40,7 +40,7 @@ function fileCursorFilters(
 
 /**
  * GET /api/workspaces/[id]/files — List workspace files: one bounded page with `nextCursor`
- * when any paging param is sent, else the whole scope exactly as before paging existed.
+ * when any paging param is sent, else the whole scope.
  */
 export const GET = defineInternalJsonRoute({
   contract: listWorkspaceFilesContract,

apps/sim/lib/api/contracts/workspace-files.ts

@@ -32,10 +32,8 @@ export const workspaceFileParamsSchema = workspaceFilesParamsSchema.extend({
 /** The fields a paged list sorts by: the v2 list's, which the shared keyset implements. */
 const WORKSPACE_FILE_SORT_FIELDS = ['name', 'size', 'uploadedAt', 'updatedAt'] as const
 
-/** The largest page `GET /api/workspaces/[id]/files` serves when paging. */
 const MAX_WORKSPACE_FILE_PAGE_SIZE = 500
 
-/** The page size a paged list request that omits `limit` gets. */
 export const DEFAULT_WORKSPACE_FILE_PAGE_SIZE = 100
 
 /** A folder filter in the browser's addressing: `root` for the workspace root, else a folder id. */
@@ -45,7 +43,7 @@ const workspaceFileFolderFilterSchema = z
 
 /**
  * The list's paging parameters. Sending any of them asks for one bounded page (default sort
- * `uploadedAt` ascending, the unpaged order, and 100 files) answered with `nextCursor`; sending
+ * `uploadedAt` ascending, the unpaged order, and {@link DEFAULT_WORKSPACE_FILE_PAGE_SIZE} files) answered with `nextCursor`; sending
  * none keeps the unpaged response, which returns the whole scope.
  */
 export const WORKSPACE_FILE_PAGE_PARAMS = [
@@ -212,7 +210,6 @@ const workspaceFileSuccessSchema = z.object({
   success: z.boolean(),
 })
 
-/** The body every file-list read answers with. */
 const workspaceFilesResponseSchema = workspaceFileSuccessSchema.extend({
   files: z.array(workspaceFileRecordSchema),
 })
@@ -266,7 +263,6 @@ export const searchWorkspaceFilesContract = defineRouteContract({
   response: { mode: 'json', schema: workspaceFilesResponseSchema },
 })
 
-/** The most entries each of a lookup's `ids`, `keys`, and `references` may carry. */
 const MAX_WORKSPACE_FILE_LOOKUP_ENTRIES = 100
 
 const lookupEntriesSchema = (field: string) =>

apps/sim/lib/uploads/contexts/workspace/file-manager.ts

@@ -1821,7 +1821,6 @@ export async function listWorkspaceFiles(
   }
 }
 
-/** The column each timestamp sort orders on. */
 const TIMESTAMP_SORT_COLUMNS = {
   uploadedAt: workspaceFiles.uploadedAt,
   updatedAt: workspaceFiles.updatedAt,

apps/sim/lib/workspace-files/__integration__/file-listing.integration.ts

@@ -5,7 +5,6 @@
  */
 import { db } from '@sim/db'
 import { permissions, user, workspace, workspaceFiles } from '@sim/db/schema'
-import { explainCaptured } from '@sim/db/testing/explain'
 import { assertDisposableTestDatabaseUrl } from '@sim/db/testing/test-infrastructure'
 import { deleteWorkspaceFixture, insertWorkspaceFixture } from '@sim/db/testing/workspace-fixtures'
 import { generateId } from '@sim/utils/id'
@@ -175,11 +174,9 @@ describe('bounded workspace file reads in PostgreSQL', () => {
       INSERT INTO folder (id, name, user_id, workspace_id, resource_type, parent_id)
         VALUES (${folders.deep}, 'Deep', ${alice}, ${workspaceId}, 'file', ${folders.sub})`)
 
-    /**
-     * Ties on every sort key: the same name in different folders, equal sizes, and timestamps
-     * equal to the microsecond or distinct only below the millisecond — where ordering on the raw
-     * column and ordering on its millisecond truncation disagree.
-     */
+    // Ties on every sort key: the same name in different folders, equal sizes, and timestamps
+    // equal to the microsecond or distinct only below the millisecond — where ordering on the raw
+    // column and ordering on its millisecond truncation disagree.
     const t = '2026-03-01T10:00:00.123'
     for (const seed of [
       {
@@ -293,14 +290,6 @@ describe('bounded workspace file reads in PostgreSQL', () => {
       ])
       expect([...firstPage.map((row) => row.id), ...resumed]).toEqual(legacyOrder)
     })
-
-    it('rejects a cursor value the sort cannot hold as a validation error', async () => {
-      await expect(
-        page({ sortBy: 'uploadedAt', after: ['not-a-date', 'wf_x'] })
-      ).rejects.toMatchObject({
-        code: 'validation',
-      })
-    })
   })
 
   describe('folder filters by id', () => {
@@ -358,45 +347,6 @@ describe('bounded workspace file reads in PostgreSQL', () => {
         })
       ).rejects.toMatchObject({ code: 'validation' })
     })
-
-    /**
-     * The folder predicate must be spelled on `coalesce(folder_id, '')`: that is the key the
-     * `(workspace_id, coalesce(folder_id, ''), original_name)` index leads with, and a name-sorted
-     * folder page that cannot seek it reads every live file the workspace holds.
-     */
-    it('seeks the folder name index for a name-sorted root or folder page', async () => {
-      await db.execute(sql`
-        INSERT INTO ${workspaceFiles} (id, key, user_id, workspace_id, folder_id, context, original_name, content_type, size_bytes)
-        SELECT 'wf_pad_' || n || '_' || ${workspaceId}, 'pad/' || n || '/' || ${workspaceId}, ${alice},
-          ${workspaceId}, CASE WHEN n % 2 = 0 THEN ${folders.media} END, 'workspace', 'pad-' || n || '.txt',
-          'text/plain', 1
-        FROM generate_series(1, 3000) AS n`)
-      await db.execute(sql`ANALYZE ${workspaceFiles}`)
-      try {
-        for (const folderId of [null, folders.media]) {
-          const nodes = await explainCaptured(
-            db,
-            () =>
-              queryWorkspaceFiles(workspaceId, {
-                folderId,
-                sortBy: 'name',
-                sortOrder: 'asc',
-                limit: 50,
-                after: ['pad-1500.txt', 'wf_x'],
-              }),
-            { match: /order by/ }
-          )
-          const scan = nodes.find(
-            (node) => node['Index Name'] === 'workspace_files_workspace_folder_name_active_unique'
-          )
-          expect(scan?.['Index Cond']).toMatch(/COALESCE\(folder_id.*original_name >=/)
-        }
-      } finally {
-        await db.execute(
-          sql`DELETE FROM ${workspaceFiles} WHERE id LIKE 'wf_pad_%' AND workspace_id = ${workspaceId}`
-        )
-      }
-    })
   })
 
   describe('name search', () => {
@@ -474,13 +424,14 @@ describe('bounded workspace file reads in PostgreSQL', () => {
       })
 
     it('rolls each child folder subtree up, excluding deleted files', async () => {
-      expect((await stats(null)).folders).toEqual(
+      const atRoot = (await stats(null)).folders
+      expect(atRoot).toHaveLength(2)
+      expect(atRoot).toEqual(
         expect.arrayContaining([
           { folderId: folders.docs, fileCount: 4, sizeBytes: 100 + 200 + 400 + 1000 },
           { folderId: folders.media, fileCount: 1, sizeBytes: 50 },
         ])
       )
-      expect((await stats(null)).folders).toHaveLength(2)
       expect((await stats(folders.docs)).folders).toEqual([
         { folderId: folders.sub, fileCount: 2, sizeBytes: 1400 },
       ])
@@ -495,20 +446,21 @@ describe('bounded workspace file reads in PostgreSQL', () => {
 
   describe('authorization', () => {
     it('serves a read member and refuses a non-member on every read', async () => {
-      await expect(page({}, { userId: bob })).resolves.toBeDefined()
-      await expect(page({}, { userId: carol })).rejects.toBeDefined()
+      expect((await page({}, { userId: bob })).files).toHaveLength(files.length)
+      const refused = { code: 'forbidden' }
+      await expect(page({}, { userId: carol })).rejects.toMatchObject(refused)
       await expect(
         lookupWorkspaceFiles.execute({
           principal: session(carol),
           input: { workspaceId, ids: ['wf_x'] },
         })
-      ).rejects.toBeDefined()
+      ).rejects.toMatchObject(refused)
       await expect(
         getWorkspaceFileFolderStats.execute({
           principal: session(carol),
           input: { workspaceId, parentId: null },
         })
-      ).rejects.toBeDefined()
+      ).rejects.toMatchObject(refused)
     })
   })
 })

apps/sim/lib/workspace-files/application/list-workspace-files.ts

@@ -187,7 +187,7 @@ export const getWorkspaceFileFolderStats = defineAuthorizedWorkspaceFileUseCase(
       return { folders: [] }
     }
     const rows = [...folderIndex.rowById.values()]
-    /** One child index for every subtree: `resolveFolderScope` would rebuild it per child. */
+    // One child index for every subtree: `resolveFolderScope` would rebuild it per child.
     const childrenByParent = indexFolderChildren(rows)
     const subtrees = rows
       .filter((row) => (row.parentId ?? null) === input.parentId)