fix(docs): stop a comment hijacking the id scan, unhang a Firecrawl reference

The depth-1 walk copied from the raw source at indices where the blanked
copy was at depth 1, so 'id:' inside a string value or a comment landed in
the scanned text and won the first match. With the keep-bias that now means
a phantom id can retain a param the block never exposes. Matching runs on
the blanked text and reads the literal back through a source-index map. No
block in the repo trips this today -- verified across all 305 -- so this is
a latent fix.

Removing the unsettable scrapeOptions row left five Firecrawl Search output
descriptions referencing a name that no longer appears on the page. They
now describe the response condition instead. Pointing them at 'formats' was
not an option: that subBlock is conditioned on scrape/parse/batch_scrape and
the search tool declares no such param, so it would have swapped one
dangling reference for another.

Author: waleedlatif1

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

@@ -167,11 +167,11 @@ Search for information on the web using Firecrawl
 |   ↳ `title` | string | Search result title from search engine |
 |   ↳ `description` | string | Search result description/snippet from search engine |
 |   ↳ `url` | string | URL of the search result |
-|   ↳ `markdown` | string | Page content in markdown \(when scrapeOptions.formats includes "markdown"\) |
-|   ↳ `html` | string | Processed HTML content \(when scrapeOptions.formats includes "html"\) |
-|   ↳ `rawHtml` | string | Unprocessed raw HTML \(when scrapeOptions.formats includes "rawHtml"\) |
-|   ↳ `links` | array | Links found on the page \(when scrapeOptions.formats includes "links"\) |
-|   ↳ `screenshot` | string | Screenshot URL \(expires after 24 hours, when scrapeOptions.formats includes "screenshot"\) |
+|   ↳ `markdown` | string | Page content in markdown, present only when the search result includes scraped page content |
+|   ↳ `html` | string | Processed HTML content, present only when the search result includes scraped page content |
+|   ↳ `rawHtml` | string | Unprocessed raw HTML, present only when the search result includes scraped page content |
+|   ↳ `links` | array | Links found on the page, present only when the search result includes scraped page content |
+|   ↳ `screenshot` | string | Screenshot URL \(expires after 24 hours\), present only when the search result includes a page screenshot |
 |   ↳ `metadata` | object | Metadata about the search result page |
 |     ↳ `title` | string | Page title |
 |     ↳ `description` | string | Page meta description |

apps/sim/tools/firecrawl/types.ts

@@ -135,29 +135,33 @@ export const SEARCH_RESULT_OUTPUT_PROPERTIES = {
   url: { type: 'string', description: 'URL of the search result' },
   markdown: {
     type: 'string',
-    description: 'Page content in markdown (when scrapeOptions.formats includes "markdown")',
+    description:
+      'Page content in markdown, present only when the search result includes scraped page content',
     optional: true,
   },
   html: {
     type: 'string',
-    description: 'Processed HTML content (when scrapeOptions.formats includes "html")',
+    description:
+      'Processed HTML content, present only when the search result includes scraped page content',
     optional: true,
   },
   rawHtml: {
     type: 'string',
-    description: 'Unprocessed raw HTML (when scrapeOptions.formats includes "rawHtml")',
+    description:
+      'Unprocessed raw HTML, present only when the search result includes scraped page content',
     optional: true,
   },
   links: {
     type: 'array',
-    description: 'Links found on the page (when scrapeOptions.formats includes "links")',
+    description:
+      'Links found on the page, present only when the search result includes scraped page content',
     optional: true,
     items: { type: 'string', description: 'URL found on the page' },
   },
   screenshot: {
     type: 'string',
     description:
-      'Screenshot URL (expires after 24 hours, when scrapeOptions.formats includes "screenshot")',
+      'Screenshot URL (expires after 24 hours), present only when the search result includes a page screenshot',
     optional: true,
   },
   metadata: SEARCH_METADATA_OUTPUT,

scripts/generate-docs.test.ts

@@ -154,6 +154,24 @@ describe('subBlock param extraction', () => {
     }
   })
 
+  it('ignores an id inside a comment or string literal at the top level of a subBlock', () => {
+    expect(
+      extractUserSettableParamIds(`subBlocks: [\n  { // id: 'ghost',\n    id: 'real' },\n],`)
+    ).toEqual(['real'])
+
+    expect(
+      extractUserSettableParamIds(
+        `subBlocks: [\n  { placeholder: "id: 'ghost'",\n    id: 'real' },\n],`
+      )
+    ).toEqual(['real'])
+
+    expect(
+      extractUserSettableParamIds(
+        `subBlocks: [\n  { placeholder: "canonicalParamId: 'ghost'",\n    id: 'real',\n    canonicalParamId: 'canonical' },\n],`
+      )
+    ).toEqual(['real', 'canonical'])
+  })
+
   it('throws when the subBlocks array holds literal objects but yields no ids', () => {
     expect(() =>
       extractUserSettableParamIds(`subBlocks: [\n  { title: 'No id here' },\n],`)

scripts/generate-docs.ts

@@ -702,6 +702,7 @@ export function extractUserSettableParamIds(blockContent: string, blockName = 'b
 
     let depth = 0
     let topLevel = ''
+    const sourceIndices: number[] = []
     for (let k = i; k < objectEnd; k++) {
       const char = scannable[k]
       if (char === '{' || char === '[') {
@@ -712,13 +713,31 @@ export function extractUserSettableParamIds(blockContent: string, blockName = 'b
         depth--
         continue
       }
-      if (depth === 1) topLevel += blockContent[k]
+      if (depth === 1) {
+        topLevel += char
+        sourceIndices.push(k)
+      }
+    }
+
+    /**
+     * Matching runs on the blanked characters, so an `id:` sitting inside a string value or a
+     * `//` comment cannot be mistaken for the subBlock's own id. Blanking keeps a string's
+     * quotes and its length, so the matched literal's value is read back character by character
+     * from the original content at the indices the blanked copy matched at.
+     */
+    const readLiteral = (match: RegExpExecArray): string => {
+      const valueStart = match.index + match[0].length - 1 - match[1].length
+      let value = ''
+      for (let offset = 0; offset < match[1].length; offset++) {
+        value += blockContent[sourceIndices[valueStart + offset]]
+      }
+      return value
     }
 
     const idMatch = /\bid\s*:\s*['"]([^'"]+)['"]/.exec(topLevel)
-    if (idMatch) ids.add(idMatch[1])
+    if (idMatch) ids.add(readLiteral(idMatch))
     const canonicalMatch = /\bcanonicalParamId\s*:\s*['"]([^'"]+)['"]/.exec(topLevel)
-    if (canonicalMatch) ids.add(canonicalMatch[1])
+    if (canonicalMatch) ids.add(readLiteral(canonicalMatch))
 
     i = objectEnd
   }