fix(types): allow global.Netlify declaration merging (#494)

* docs: fix misleading comments

* fix(types): allow `global.Netlify` declaration merging

This fixes a TypeScript error that occurs when both `@netlify/[email protected]` and
`@netlify/functions` are installed in a project (with `skipLibCheck: false`).

It would fail with:

```
Error: TS2451: Cannot redeclare block-scoped variable 'Netlify'
```

See for example #489.

You would think it wouldn't be valid to use both those packages at once, but TypeScript global
module augmentation is truly _global_ - it doesn't care where you import a package that performs
global module augmentation; your whole TS project is compiled/typechecked as one program, unless you
explicitly configure things completely separately for your `./netlify/functions` vs.
`./netlify/edge-functions` vs. `src/`... which pretty much no one does.

TypeScript allows multiple `var` declarations in a scope to merge, but `const` declarations are
cannot be redeclared. When both packages declare `global.Netlify`, they must both use `var` for the
declarations to merge successfully.

We were actually already doing this correctly, but unfortunately there was a comment that was lying
about _why_ (and there was no type test covering this). This led me to change it to `const` in
#434.

I went down a rabbit hole trying to add a regression type test for this but I had to cut my losses
after running into some issues.

Author: serhalp

packages/edge-functions/prod/src/main.ts

@@ -1,9 +1,8 @@
 import type { NetlifyGlobal } from '@netlify/types'
 
 declare global {
-  // Using `var` so that the declaration is hoisted in such a way that we can
-  // reference it before it's initialized.
-
+  // Using `var` instead of `const` to allow TypeScript declaration merging.
+  // Multiple packages can declare the same global with `var`, but `const` cannot be redeclared.
   var Netlify: NetlifyGlobal
 }
 

packages/functions/prod/src/main.ts

@@ -1,7 +1,9 @@
 import type { NetlifyGlobal } from '@netlify/types'
 
 declare global {
-  const Netlify: NetlifyGlobal
+  // Using `var` instead of `const` to allow TypeScript declaration merging.
+  // Multiple packages can declare the same global with `var`, but `const` cannot be redeclared.
+  var Netlify: NetlifyGlobal
 }
 
 export { builder } from './lib/builder.js'

packages/runtime/src/lib/globals.ts

@@ -4,9 +4,8 @@ import type { Context, NetlifyGlobal } from '@netlify/types'
 import { GlobalScope } from './util.js'
 
 declare global {
-  // Using `var` so that the declaration is hoisted in such a way that we can
-  // reference it before it's initialized.
-
+  // Using `var` instead of `const` to allow TypeScript declaration merging.
+  // Multiple packages can declare the same global with `var`, but `const` cannot be redeclared.
   var Netlify: NetlifyGlobal
 }