docs(generator): name the load-bearing newline rule and report an unscannable source

- Record why '\\n' is in REGEX_ALLOWED_AFTER: formatters emit a binary '/' at
  end-of-line, so every line-leading '/' in blocks/*.ts is a real regex, including
  the ones in table.ts and table_v2.ts. Removing it silently mis-scans those two.
- Split a scanner failure out of the spread-only 'ids: null' case. Both scans come
  back empty for the same reason when blankStringsAndComments bails, so the mapper's
  renames were dropped with no warning; it now reports a parseError and warns. The
  spread case is unchanged, and its TSDoc no longer claims a cause that was false.
- Route every catalog sort through an exported compareCatalogNames so the ordering
  test exercises the generator's comparator instead of re-deriving it, and match
  localeCompare arguments whole so localeCompare() and a variable locale are caught.
- Note that downloadServableFileFromStorage guarantees a non-empty content type, so
  the Vanta mimeType fallback chain reads as deliberately defensive.

Artifacts regenerate byte-identically and the generator warning set is unchanged.

Author: waleedlatif1

apps/sim/lib/internal/vanta/file-input.ts

@@ -70,6 +70,11 @@ export async function resolveVantaUploadFile(
         signal: context.signal,
       })
       context.signal?.throwIfAborted()
+      /**
+       * Every return path of `downloadServableFileFromStorage` yields a non-empty content
+       * type, so `resolved.contentType` always wins. The remaining operands are defensive
+       * fallbacks kept in place in case that guarantee is ever relaxed.
+       */
       return {
         buffer: resolved.buffer,
         fileName: input.fileName || userFile.name,

scripts/generate-docs.test.ts

@@ -2,6 +2,7 @@ import fs from 'fs'
 import path from 'path'
 import { describe, expect, it } from 'vitest'
 import {
+  compareCatalogNames,
   extractAllBlockConfigs,
   extractBlockSuppliedParamIds,
   extractToolInfo,
@@ -698,27 +699,72 @@ describe('mapper param shapes', () => {
   })
 })
 
+describe('a source the scanner cannot get through is reported, not swallowed', () => {
+  /**
+   * When `blankStringsAndComments` bails, both the `subBlocks` scan and the mapper scan come
+   * back empty for the same reason. Reported as a plain `ids: null` that is indistinguishable
+   * from a spread-only `subBlocks` array, the block's mapper renames are dropped in silence.
+   */
+  const unterminated = `subBlocks: [{ id: 'a' }],
+    tools: { config: { params: (p) => ({ renamedByMapper: p.a }) } },
+    longDescription: 'never closed`
+
+  it('sets parseError so the caller warns', () => {
+    const supplied = extractBlockSuppliedParamIds(unterminated, 'GhostBlock')
+
+    expect(supplied.parseError).not.toBeNull()
+    expect(supplied.parseError).toMatch(/GhostBlock: source ends inside an unterminated/)
+    expect(supplied.ids).toBeNull()
+  })
+
+  it('still reports null with no parseError for a spread-only subBlocks array', () => {
+    const supplied = extractBlockSuppliedParamIds(
+      "subBlocks: [...NotionBlock.subBlocks], tools: { config: { params: (p) => ({ renamedByMapper: p.a }) } },",
+      'SpreadBlock'
+    )
+
+    expect(supplied.parseError).toBeNull()
+    expect(supplied.ids).toBeNull()
+    expect(supplied.mapperIds).toContain('renamedByMapper')
+  })
+})
+
 describe('the generated catalog ordering is locale-independent', () => {
   /**
    * `localeCompare` with no locale argument uses the runtime default, which varies with `LANG`
    * and the ICU build. Against the real catalog names, `tr-TR` (dotted/dotless I), `lt-LT`,
    * `cs-CZ` (the `ch` digraph) and `et-EE` each reorder the array, so a contributor on one of
    * those locales would regenerate a different `integrations.json` and fail CI with no obvious
-   * cause. The generator pins `en-US`; this asserts the committed artifact matches that order.
+   * cause.
    */
-  it('sorts integrations.json the way an explicit en-US comparator would', () => {
+  it('pins the generator comparator to en-US regardless of the runtime default', () => {
+    /** `I` sorts after `i` in `en-US` but before it in `tr-TR`, which has a dotless `ı`. */
+    expect(compareCatalogNames('Intercom', 'incident.io')).toBeGreaterThan(0)
+    /** `ch` is a single letter after `h` in `cs-CZ`; in `en-US` it stays under `c`. */
+    expect(compareCatalogNames('Chargebee', 'HubSpot')).toBeLessThan(0)
+  })
+
+  it('sorts integrations.json with the generator comparator', () => {
     const catalogPath = path.join(__dirname, '../packages/deployment-config/src/integrations.json')
     const names = (
       JSON.parse(fs.readFileSync(catalogPath, 'utf-8')).integrations as Array<{ name: string }>
     ).map(({ name }) => name)
 
-    expect(names).toEqual([...names].sort((a, b) => a.localeCompare(b, 'en-US')))
+    expect(names).toEqual([...names].sort(compareCatalogNames))
   })
 
+  /**
+   * Every `localeCompare` in the generator must name its locale as a literal. A bare
+   * `localeCompare()`, `localeCompare(b)` or a locale read from a variable all fall back to
+   * the runtime default, so the arguments are matched whole rather than pattern-matched.
+   */
   it('leaves no unpinned localeCompare in the generator', () => {
     const source = fs.readFileSync(path.join(__dirname, 'generate-docs.ts'), 'utf-8')
 
-    expect(source).not.toMatch(/localeCompare\(\s*[A-Za-z_$][\w$.]*\s*\)/)
+    const calls = [...source.matchAll(/\blocaleCompare\(([^)]*)\)/g)].map(([, args]) => args)
+
+    expect(calls.length).toBeGreaterThan(0)
+    for (const args of calls) expect(args).toMatch(/,\s*'[a-zA-Z-]+'\s*$/)
   })
 })
 

scripts/generate-docs.ts

@@ -652,7 +652,7 @@ function writeIconMapping(iconMapping: Record<string, IconRef>): void {
 
     // Generate mapping with direct references (no dynamic access for tree shaking)
     const mappingEntries = Object.entries(withAliases)
-      .sort(([a], [b]) => a.localeCompare(b, 'en-US'))
+      .sort(([a], [b]) => compareCatalogNames(a, b))
       .map(([blockType, iconRef]) => `  ${formatIconMapKey(blockType)}: ${iconRef.name},`)
       .join('\n')
 
@@ -1078,6 +1078,21 @@ export function extractBlockSuppliedParamIds(
   blockContent: string,
   blockName = 'block'
 ): BlockSuppliedParams {
+  /**
+   * A source the blanking scanner cannot get through — it ends inside an unterminated string,
+   * template literal or comment — makes both scans below report "nothing found" for the same
+   * reason. It is caught here so it is reported as a parse failure. Left to the branches below
+   * it would be indistinguishable from a spread-only `subBlocks` array whose block has no
+   * mapper, and the block's renames would be dropped without a word.
+   */
+  if (blankStringsAndComments(blockContent) === null) {
+    return {
+      ids: null,
+      mapperIds: [],
+      parseError: `${blockName}: source ends inside an unterminated string, template literal or comment, so neither its subBlocks array nor its params mapper could be read`,
+    }
+  }
+
   const mapperIds = extractMapperWrittenParamIds(blockContent)
 
   try {
@@ -1255,7 +1270,29 @@ function extractAuthType(blockContent: string): 'oauth' | 'api-key' | 'none' {
   return 'none'
 }
 
-/** Characters after which a `/` begins a regex literal rather than a division. */
+/**
+ * The catalog and every generated mapping are sorted with an explicit `en-US` collation.
+ * `localeCompare` with no locale uses the runtime default, which varies with `LANG` and the
+ * ICU build: `tr-TR`, `lt-LT`, `cs-CZ` and `et-EE` each reorder the real integration names, so
+ * a contributor on one of those locales would regenerate a different artifact and fail CI with
+ * no obvious cause.
+ */
+export function compareCatalogNames(a: string, b: string): number {
+  return a.localeCompare(b, 'en-US')
+}
+
+/**
+ * Characters after which a `/` begins a regex literal rather than a division.
+ *
+ * `'\n'` is deliberate and load-bearing: a line-leading `/` is treated as opening a regex.
+ * Prettier and Biome both emit a binary `/` at end-of-line, never at the start of the next
+ * one, so in this repo's formatted sources every line-leading `/` really is a regex — all 17
+ * occurrences across `apps/sim/blocks/blocks/*.ts` are, including the ones at
+ * `blocks/table.ts:31` and `blocks/table_v2.ts:37` that this set exists to get right. Removing
+ * `'\n'` makes those two blocks lex as division and silently mis-scan. It is a deliberate
+ * trade: a hand-wrapped `b` newline `/ c / d` would be blanked as a regex body, which no
+ * formatted file in this repo produces.
+ */
 const REGEX_ALLOWED_AFTER = new Set([
   '(',
   ',',
@@ -1565,7 +1602,7 @@ function writeIntegrationsIconMapping(iconMapping: Record<string, IconRef>): voi
 
     const imports = renderIconImports(Object.values(iconMapping))
     const mappingEntries = Object.entries(iconMapping)
-      .sort(([a], [b]) => a.localeCompare(b, 'en-US'))
+      .sort(([a], [b]) => compareCatalogNames(a, b))
       .map(([blockType, iconRef]) => `  ${formatIconMapKey(blockType)}: ${iconRef.name},`)
       .join('\n')
 
@@ -1740,7 +1777,7 @@ async function writeIntegrationsJson(iconMapping: Record<string, IconRef>): Prom
       }
     }
 
-    integrations.sort((a, b) => a.name.localeCompare(b.name, 'en-US'))
+    integrations.sort((a, b) => compareCatalogNames(a.name, b.name))
 
     const jsonPath = path.join(INTEGRATIONS_CATALOG_PATH, 'integrations.json')
     // `JSON.stringify` always expands every array across multiple lines, but Biome's
@@ -1961,12 +1998,13 @@ function extractBlockConfigFromContent(
       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.
+       * With `parseError` null, the only remaining cause is a `subBlocks` array holding just
+       * spreads of fields arrays this scanner cannot follow — a source the scanner could not
+       * get through at all is reported as a `parseError` by `extractBlockSuppliedParamIds` and
+       * handled above. 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: the array itself parsed
+       * fine, and every field it names is documented through the spread source's own page.
        */
       userSettableParamIds =
         baseSettableParamIds.length > 0
@@ -4454,7 +4492,7 @@ function groupTriggersByProvider(
     }
     groups.set(
       provider,
-      [...byName.values()].sort((a, b) => a.name.localeCompare(b.name, 'en-US'))
+      [...byName.values()].sort((a, b) => compareCatalogNames(a.name, b.name))
     )
   }
   return groups