`deno test --doc`: restrict permissions using shebangs

[lowlighter]

Currently seems like shebang in example testing are not supported (cause a parsing error).

Also it'd be nice if it could also parse the permissions flags and forwards them to Deno.test({ permissions })

/**
 * Documentation of my function.
 *
 * @example Usage
 * ```ts
 * #!/usr/bin/env -S deno run --allow-read
 * foo("bar")
 * ```
 * @example Missing permissions
 * ```ts 
 * #!/usr/bin/env -S deno run --deny-read
 * foo("bar") // failing test
 * ```
 */
export function foo(s:string) {
  return Deno.readTextFileSync(import.meta.filename!)
}

Because currently these tests are running with the full current permissions, which may not necessary be wanted. It'll also helps documenting which permissions would be required to end users too

Also if the permissions feature gets implemented, I think the default for flags should be "inherit" rather than true. For example, when running deno test --doc --allow-read=/tmp, if the shebang in the doc test is #!/usr/bin/env -S deno run --allow-read the --allow-read would be converted to { permissions: { read: "inherit" } } rather than { permissions: { read: true } } (so the doc test would actually be run with --allow-read=/tmp too)

[lucacasonato]

Split the syntax error out into https://github.com/denoland/deno/issues/26018.