fix(docs): blank comments whole, and fail loudly when subBlock parsing breaks

blankStringsAndComments kept the first and last character of every match.
That is correct for a quoted string, where both are delimiters, but for a
'//' comment the last character is arbitrary source text -- so a
commented-out '//   options: [' left an unbalanced bracket inside the
subBlocks span, findMatchingClose returned -1, and the extractor reported
that the block exposes nothing.

google_drive lost three user-settable mimeType rows that way. The block
renders mimeType as an Export Format dropdown.

A parse failure and 'this block exposes nothing' were indistinguishable,
and the fallback was the destructive branch. Parsing now throws a
SubBlockParseError when the bracket scan fails or when an array holding
literal objects yields no ids; the call site reports it and exits non-zero
in both generate and check mode rather than dropping the page.

Author: waleedlatif1

apps/docs/content/docs/en/integrations/google_drive.mdx

@@ -153,6 +153,7 @@ Get content from a file in Google Drive with complete metadata (exports Google W
 | Parameter | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `fileId` | string | Yes | The ID of the file to get content from |
+| `mimeType` | string | No | The MIME type to export Google Workspace files to \(optional\) |
 | `includeRevisions` | boolean | No | Whether to include revision history in the metadata \(default: true, returns first 100 revisions\) |
 
 #### Output
@@ -280,6 +281,7 @@ Upload a file to Google Drive with complete metadata returned
 | `fileName` | string | Yes | The name of the file to upload |
 | `file` | file | No | Binary file to upload \(UserFile object\) |
 | `content` | string | No | Text content to upload \(use this OR file, not both\) |
+| `mimeType` | string | No | The MIME type of the file to upload \(auto-detected from file if not provided\) |
 | `folderSelector` | string | No | Google Drive folder ID to upload the file to \(e.g., 1ABCxyz...\) |
 
 #### Output
@@ -349,6 +351,7 @@ Download a file from Google Drive with complete metadata (exports Google Workspa
 | Parameter | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `fileId` | string | Yes | The ID of the file to download |
+| `mimeType` | string | No | The MIME type to export Google Workspace files to \(optional\) |
 | `fileName` | string | No | Optional filename override |
 | `includeRevisions` | boolean | No | Whether to include revision history in the metadata \(default: true, returns first 100 revisions\) |
 

scripts/generate-docs.test.ts

@@ -118,3 +118,50 @@ describe('hidden tool params in the Input table', () => {
     )
   })
 })
+
+describe('subBlock param extraction', () => {
+  const blockSource = (blockFile: string) =>
+    fs.readFileSync(path.join(import.meta.dirname, '../apps/sim/blocks/blocks', blockFile), 'utf-8')
+
+  it('extracts ids from a block whose subBlocks array contains commented-out code', () => {
+    const ids = extractUserSettableParamIds(blockSource('google_drive.ts'))
+
+    expect(ids).toContain('operation')
+    expect(ids).toContain('mimeType')
+    expect(ids).toContain('fileName')
+    expect(ids).toContain('uploadFolderSelector')
+  })
+
+  it('extracts ids past a commented-out subBlock that ends a line on an open bracket', () => {
+    const ids = extractUserSettableParamIds(blockSource('human_in_the_loop.ts'))
+
+    expect(ids).toContain('notification')
+    expect(ids).toContain('inputFormat')
+  })
+
+  it('returns no ids for blocks whose subBlocks array holds only spreads', () => {
+    for (const blockFile of [
+      'imap.ts',
+      'chat_trigger.ts',
+      'generic_webhook.ts',
+      'manual_trigger.ts',
+      'circleback.ts',
+      'rss.ts',
+      'sim_workspace_event.ts',
+    ]) {
+      expect(extractUserSettableParamIds(blockSource(blockFile))).toEqual([])
+    }
+  })
+
+  it('throws when the subBlocks array holds literal objects but yields no ids', () => {
+    expect(() =>
+      extractUserSettableParamIds(`subBlocks: [\n  { title: 'No id here' },\n],`)
+    ).toThrow(/subBlocks/)
+  })
+
+  it('throws when the subBlocks array bracket scan fails', () => {
+    expect(() => extractUserSettableParamIds(`subBlocks: [\n  { id: 'operation' },\n`)).toThrow(
+      /subBlocks/
+    )
+  })
+})

scripts/generate-docs.ts

@@ -648,6 +648,17 @@ ${mappingEntries}
   }
 }
 
+/**
+ * Raised when a block's `subBlocks` array is present but cannot be read. Distinguishes
+ * a parse failure from a block that genuinely exposes no fields — both used to surface
+ * as an empty array, and the empty array silently strips documented rows.
+ */
+class SubBlockParseError extends Error {
+  override name = 'SubBlockParseError'
+}
+
+const subBlockParseFailures: string[] = []
+
 /**
  * Collects the param names a block exposes to the user through its own `subBlocks`.
  *
@@ -662,14 +673,18 @@ ${mappingEntries}
  * cannot skew it; only depth-1 properties of each subBlock are read, so `id` fields on
  * nested `options`/`condition` objects are never mistaken for the subBlock's own id.
  */
-export function extractUserSettableParamIds(blockContent: string): string[] {
+export function extractUserSettableParamIds(blockContent: string, blockName = 'block'): string[] {
   const scannable = blankStringsAndComments(blockContent)
   const subBlocksMatch = /subBlocks\s*:\s*\[/.exec(scannable)
   if (!subBlocksMatch) return []
 
   const arrayStart = subBlocksMatch.index + subBlocksMatch[0].length - 1
   const arrayEnd = findMatchingClose(scannable, arrayStart, '[', ']')
-  if (arrayEnd === -1) return []
+  if (arrayEnd === -1) {
+    throw new SubBlockParseError(
+      `${blockName}: found a subBlocks array but could not locate its closing bracket`
+    )
+  }
 
   const ids = new Set<string>()
   let i = arrayStart + 1
@@ -705,6 +720,18 @@ export function extractUserSettableParamIds(blockContent: string): string[] {
     i = objectEnd
   }
 
+  /**
+   * Zero ids is a legitimate answer only for a block whose array is nothing but
+   * `...getTrigger(...).subBlocks` spreads. If the array holds an object literal and
+   * still yields nothing, the scan failed — and the caller's fallback (strip every
+   * hidden param from the page) is the destructive one, so fail instead of guessing.
+   */
+  if (ids.size === 0 && scannable.slice(arrayStart, arrayEnd).includes('{')) {
+    throw new SubBlockParseError(
+      `${blockName}: subBlocks array holds object literals but no id was extracted`
+    )
+  }
+
   return [...ids]
 }
 
@@ -882,7 +909,17 @@ function extractAuthType(blockContent: string): 'oauth' | 'api-key' | 'none' {
 function blankStringsAndComments(content: string): string {
   return content.replace(
     /(['"`])(?:\\[\s\S]|(?!\1)[^\\])*\1|\/\/[^\n]*|\/\*[\s\S]*?\*\//g,
-    (match) => match[0] + match.slice(1, -1).replace(/[^\n]/g, ' ') + match[match.length - 1]
+    (match: string, quote: string | undefined) => {
+      const blanked = match.replace(/[^\n]/g, ' ')
+      /**
+       * A comment has no delimiters worth preserving, so it is blanked whole. Keeping
+       * its final character would leak arbitrary source text — commented-out code ending
+       * in `[` or `{` leaves an unbalanced bracket that derails every scan downstream.
+       * A quoted string keeps its own quotes so callers can still see where it began.
+       */
+      if (quote === undefined) return blanked
+      return quote + blanked.slice(1, -1) + quote
+    }
   )
 }
 
@@ -1396,11 +1433,20 @@ function extractBlockConfigFromContent(
 
     const operations = extractOperationsFromContent(blockContent)
     const triggerIds = extractTriggersAvailable(blockContent, fileContent)
+    let ownSettableParamIds: string[] = []
+    try {
+      ownSettableParamIds = extractUserSettableParamIds(blockContent, blockName)
+    } catch (error) {
+      /**
+       * Recorded rather than rethrown so one unreadable block cannot drop itself from the
+       * docs entirely. `generateAllBlockDocs` fails the run on any recorded failure.
+       */
+      if (!(error instanceof SubBlockParseError)) throw error
+      subBlockParseFailures.push(error.message)
+      console.error(`✗ ${error.message}`)
+    }
     const userSettableParamIds = [
-      ...new Set([
-        ...extractUserSettableParamIds(blockContent),
-        ...((baseConfig as any)?.userSettableParamIds ?? []),
-      ]),
+      ...new Set([...ownSettableParamIds, ...((baseConfig as any)?.userSettableParamIds ?? [])]),
     ]
     const docsLink =
       extractStringPropertyFromContent(blockContent, 'docsLink', true) ||
@@ -4132,6 +4178,15 @@ async function generateAllBlockDocs() {
     // Write the integrations meta after both passes so trigger-only pages are included
     updateMetaJson()
 
+    if (subBlockParseFailures.length > 0) {
+      console.error(
+        `Could not read the subBlocks array of ${subBlockParseFailures.length} block(s):\n- ${[
+          ...new Set(subBlockParseFailures),
+        ].join('\n- ')}`
+      )
+      return false
+    }
+
     return true
   } catch (error) {
     console.error('Error generating documentation:', error)