fix(docs): report a spread-only subBlocks array as unknown, not empty

extractUserSettableParamIds answered [] for a subBlocks array whose every
element spreads a fields array it cannot follow (NotionV2Block's
`[...NotionBlock.subBlocks, ...getTrigger(x).subBlocks]`). [] asserts the
block supplies nothing, so the hidden-param filter stripped every hidden
param from every tool the block owns - silently, with no parseError and so
no warning. That is the exact false-drop the null UNKNOWN state exists to
prevent.

Return null in that case and propagate it: extractBlockSuppliedParamIds no
longer folds it into [], and the block pass no longer collapses it with
`supplied.ids ?? []`. A config-level spread base still narrows the filter to
its readable fields plus the mapper's renames; with no base the filter is
switched off. An array with at least one inline id, a genuinely empty array,
and the existing throw/warn paths are unchanged - all 8 warned blocks warn
identically and every generated page is byte-identical.

Also pin the hidden-param filter on extractToolInfo's source-parsing path,
which had no coverage at all: deleting it outright left the suite green.

Author: waleedlatif1

scripts/generate-docs.test.ts

@@ -111,6 +111,56 @@ describe('documentation input parameter parsing', () => {
     ])
   })
 
+  /**
+   * Pins the hidden-param filter on the source-parsing path in {@link extractToolInfo}. Tools
+   * with an entry in tool-metadata.ts never reach it, so it must be driven with synthetic
+   * source rather than through `getToolInfo`. Without this the filter can be deleted outright
+   * and the whole suite stays green.
+   */
+  describe('the hidden-param filter on the source-parsing path', () => {
+    const source = `
+        export const exampleTool = {
+          id: 'example_send',
+          description: 'Send an example',
+          params: {
+            message: {
+              type: 'string',
+              required: true,
+              description: 'The message',
+            },
+            apiKey: {
+              type: 'string',
+              required: true,
+              visibility: 'hidden',
+              description: 'The API key the block injects',
+            },
+            instanceUrl: {
+              type: 'string',
+              required: true,
+              visibility: 'hidden',
+              description: 'Resolved from the credential',
+            },
+          },
+          outputs: {},
+        }
+      `
+
+    const paramNames = (ids: ReadonlySet<string> | null) =>
+      extractToolInfo('example_send', source, '', '', '', ids)?.params.map(({ name }) => name)
+
+    it('drops a hidden param the block does not supply', () => {
+      expect(paramNames(new Set(['message']))).toEqual(['message'])
+    })
+
+    it('keeps a hidden param the block exposes as its own field', () => {
+      expect(paramNames(new Set(['message', 'apiKey']))).toEqual(['message', 'apiKey'])
+    })
+
+    it('keeps every param when the block-supplied set is UNKNOWN', () => {
+      expect(paramNames(null)).toEqual(['message', 'apiKey', 'instanceUrl'])
+    })
+  })
+
   it('stops at legacy request metadata after a comment', () => {
     const tool = extractToolInfo(
       'example_send',
@@ -275,18 +325,42 @@ describe('subBlock param extraction', () => {
     expect(ids).toContain('inputFormat')
   })
 
-  it('returns no ids for blocks whose subBlocks array holds only spreads', () => {
+  it('returns no ids for blocks whose subBlocks array is genuinely empty', () => {
+    for (const blockFile of ['chat_trigger.ts', 'manual_trigger.ts']) {
+      expect(extractUserSettableParamIds(blockSource(blockFile))).toEqual([])
+    }
+  })
+
+  /**
+   * The spreads name fields arrays this scanner never follows, so what the block supplies is
+   * UNKNOWN. Answering `[]` asserts the block supplies nothing, and the hidden-param filter
+   * reads that as licence to strip every hidden param from every tool the block owns — silently,
+   * with no `parseError` and so no warning. `NotionV2Block` has exactly this shape and is only
+   * harmless today because no `notion_*` tool carries a hidden param besides `accessToken`.
+   */
+  it('reports a subBlocks array of only unfollowable spreads as UNKNOWN, not empty', () => {
     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([])
+      expect(extractUserSettableParamIds(blockSource(blockFile))).toBeNull()
     }
+
+    const supplied = extractBlockSuppliedParamIds(
+      `subBlocks: [...NotionBlock.subBlocks],`,
+      'NotionV2'
+    )
+    expect(supplied.ids).toBeNull()
+    expect(supplied.parseError).toBeNull()
+  })
+
+  it('still returns the inline ids when a spread sits alongside them', () => {
+    expect(
+      extractUserSettableParamIds(`subBlocks: [...Base.subBlocks, { id: 'operation' }],`)
+    ).toEqual(['operation'])
   })
 
   it('ignores an id inside a comment or string literal at the top level of a subBlock', () => {
@@ -342,20 +416,26 @@ describe('subBlock param extraction', () => {
       ).toThrow(/SlackV2: subBlocks/)
     })
 
-    it('still returns no ids for an array of nothing but named fields arrays', () => {
+    /**
+     * The elements name fields arrays, so the array parsed fine and there is nothing to warn
+     * about — but this scanner never follows a spread, so the fields are UNKNOWN rather than
+     * absent. `[]` would be a confident wrong answer that strips every hidden param the block's
+     * tools declare.
+     */
+    it('reports an array of nothing but named fields arrays as UNKNOWN', () => {
       expect(
         extractUserSettableParamIds(
           `subBlocks: [\n  ...NotionBlock.subBlocks,\n  ...getTrigger('notion_page_created').subBlocks,\n],`,
           'NotionV2'
         )
-      ).toEqual([])
+      ).toBeNull()
 
       expect(
         extractUserSettableParamIds(
           `subBlocks: [\n  ...LinearBlock.subBlocks.filter((sb) => !sb.id?.startsWith('webhookSecret')),\n],`,
           'LinearV2'
         )
-      ).toEqual([])
+      ).toBeNull()
     })
 
     it('does not fail a block that overrides a spread subBlock instead of naming an id', () => {
@@ -364,7 +444,7 @@ describe('subBlock param extraction', () => {
           `subBlocks: [\n  ...Base.subBlocks.map((sb) => (sb.id === 'x' ? { ...sb, required: true } : sb)),\n],`,
           'OverridingV2'
         )
-      ).toEqual([])
+      ).toBeNull()
     })
 
     it('leaves a readable array alone even when it also spreads an opaque helper', () => {

scripts/generate-docs.ts

@@ -703,8 +703,16 @@ const subBlockParseWarnings = new Set<string>()
  * Brace matching runs on a blanked copy so braces inside string literals and comments
  * 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.
+ *
+ * Returns `null` for UNKNOWN — an array whose elements are all spreads of fields arrays this
+ * scanner cannot follow (`...NotionBlock.subBlocks`, `...getTrigger('x').subBlocks`). `[]` is
+ * reserved for a block that genuinely exposes no fields, because `[]` strips every hidden param
+ * from the page. Throws {@link SubBlockParseError} when the array is there but unreadable.
  */
-export function extractUserSettableParamIds(blockContent: string, blockName = 'block'): string[] {
+export function extractUserSettableParamIds(
+  blockContent: string,
+  blockName = 'block'
+): string[] | null {
   const scannable = blankStringsAndComments(blockContent)
   const keyMatch = /\bsubBlocks\s*:/.exec(scannable)
   if (!keyMatch) return []
@@ -831,10 +839,11 @@ export function extractUserSettableParamIds(blockContent: string, blockName = 'b
    * bare helper call (`...getSlackV2ActionSubBlocks()`) hides whatever fields the helper builds,
    * and used to yield a silent empty array indistinguishable from a spread-only block.
    */
-  const opaque = elementHeads
+  const segments = elementHeads
     .split(',')
     .map((segment) => segment.trim())
-    .filter((segment) => segment.length > 0 && !segment.includes('.subBlocks'))
+    .filter((segment) => segment.length > 0)
+  const opaque = segments.filter((segment) => !segment.includes('.subBlocks'))
   if (opaque.length > 0) {
     throw new SubBlockParseError(
       `${blockName}: subBlocks array yielded no ids and element${
@@ -843,6 +852,15 @@ export function extractUserSettableParamIds(blockContent: string, blockName = 'b
     )
   }
 
+  /**
+   * Every element named a fields array this scanner cannot follow, so the block's fields are
+   * UNKNOWN, not empty. Returning `[]` here would assert the block supplies nothing and strip
+   * every hidden param from its tools' Input tables with no warning — the silent false-drop the
+   * `null` state exists to prevent. Only a genuinely empty array (`subBlocks: []`) reaches the
+   * `[]` below.
+   */
+  if (segments.length > 0) return null
+
   return []
 }
 
@@ -1026,7 +1044,9 @@ export function extractMapperWrittenParamIds(blockContent: string): string[] {
 /** What {@link extractBlockSuppliedParamIds} could and could not read off a block. */
 export interface BlockSuppliedParams {
   /**
-   * Every param the block supplies, or `null` when its `subBlocks` array could not be read.
+   * Every param the block supplies, or `null` when what its `subBlocks` array contributes is
+   * unknown — either the array could not be read (`parseError` set) or it holds only spreads of
+   * fields arrays this scanner cannot follow (`parseError` null).
    *
    * `null` is UNKNOWN and is deliberately distinct from `[]`: an empty array asserts the block
    * supplies nothing, which strips every hidden param from the page, while `null` says the scan
@@ -1060,6 +1080,7 @@ export function extractBlockSuppliedParamIds(
 
   try {
     const settableIds = extractUserSettableParamIds(blockContent, blockName)
+    if (settableIds === null) return { ids: null, mapperIds, parseError: null }
     return { ids: [...new Set([...settableIds, ...mapperIds])], mapperIds, parseError: null }
   } catch (error) {
     if (!(error instanceof SubBlockParseError)) throw error
@@ -1806,8 +1827,21 @@ function extractBlockConfigFromContent(
       userSettableParamIds = fallback
     } else if (baseParamIds === null) {
       userSettableParamIds = null
+    } else if (supplied.ids === null) {
+      /**
+       * The block's `subBlocks` array holds only spreads of fields arrays this scanner cannot
+       * follow. A config-level spread base still contributes its readable fields, so the filter
+       * stays on against those plus the mapper's renames; with no base there is nothing to
+       * filter against and the filter is switched off. No warning: unlike the `parseError`
+       * cases the array itself parsed fine, and every field it names is documented through the
+       * spread source's own page.
+       */
+      userSettableParamIds =
+        baseSettableParamIds.length > 0
+          ? [...new Set([...baseSettableParamIds, ...supplied.mapperIds])]
+          : null
     } else {
-      userSettableParamIds = [...new Set([...(supplied.ids ?? []), ...baseSettableParamIds])]
+      userSettableParamIds = [...new Set([...supplied.ids, ...baseSettableParamIds])]
     }
     const docsLink =
       extractStringPropertyFromContent(blockContent, 'docsLink', true) ||