refactor(cli): use ext option to override non-js-like script extensions

Author: antongolub

docs/cli.md

@@ -13,7 +13,16 @@ assumes that it is
 an [ESM](https://nodejs.org/api/modules.html#modules_module_createrequire_filename)
 module unless the `--ext` option is specified.
 
+## Non-standard extension
+`zx` internally loads scripts via `import` API, so you can use any extension supported by the runtime (nodejs, deno, bun) or apply a [custom loader](https://nodejs.org/api/cli.html#--experimental-loadermodule).
+However, if the script has a non-js-like extension (`/^\.[mc]?[jt]sx?$/`) and the `--ext` is specified, it will be used.
 
+```bash
+zx script.zx           # Unknown file extension "\.zx"
+zx --ext=mjs script.zx # OK
+```
+
+## Markdown
 ```bash
 zx docs/markdown.md
 ```
@@ -89,10 +98,10 @@ Enable verbose mode.
 
 ## `--shell`
 
-Specify a custom shell binary.
+Specify a custom shell binary path. By default, zx refers to `bash`.
 
 ```bash
-zx --shell=/bin/bash script.mjs
+zx --shell=/bin/another/sh script.mjs
 ```
 
 ## `--prefer-local, -l`
@@ -131,7 +140,7 @@ When `cwd` option is specified, it will be used as base path:
 
 ## `--ext`
 
-Override the default (temp) script extension. Default is `.mjs`.
+Overrides the default script extension (`.mjs`).
 
 ## `--version, -v`
 

man/zx.1

@@ -24,9 +24,7 @@ prefer locally installed packages bins
 .SS --eval=<js>, -e
 evaluate script
 .SS --ext=<.mjs>
-default extension
-.SS --ext-override
-override script extensions
+script extension
 .SS --install, -i
 install dependencies
 .SS --registry=<URL>

src/cli.ts

@@ -35,6 +35,7 @@ import { randomId, bufToString } from './util.js'
 import { createRequire, type minimist } from './vendor.js'
 
 const EXT = '.mjs'
+const EXT_RE = /^\.[mc]?[jt]sx?$/
 
 isMain() &&
   main().catch((err) => {
@@ -64,8 +65,7 @@ export function printUsage() {
    --prefer-local, -l   prefer locally installed packages bins
    --cwd=<path>         set current directory
    --eval=<js>, -e      evaluate script
-   --ext=<.mjs>         default extension
-   --ext-override       override script extensions
+   --ext=<.mjs>         script extension
    --install, -i        install dependencies
    --registry=<URL>     npm registry, defaults to https://registry.npmjs.org/
    --version, -v        print current zx version
@@ -81,7 +81,7 @@ export function printUsage() {
 // prettier-ignore
 export const argv: minimist.ParsedArgs = parseArgv(process.argv.slice(2), {
   string: ['shell', 'prefix', 'postfix', 'eval', 'cwd', 'ext', 'registry', 'env'],
-  boolean: ['version', 'help', 'quiet', 'verbose', 'install', 'repl', 'experimental', 'prefer-local', 'ext-override'],
+  boolean: ['version', 'help', 'quiet', 'verbose', 'install', 'repl', 'experimental', 'prefer-local'],
   alias: { e: 'eval', i: 'install', v: 'version', h: 'help', l: 'prefer-local', 'env-file': 'env' },
   stopEarly: true,
   parseBoolean: true,
@@ -181,7 +181,7 @@ async function readScript() {
   }
 
   const { ext, base, dir } = path.parse(tempPath || scriptPath)
-  if (ext === '' || argv.extOverride) {
+  if (ext === '' || (argv.ext && !EXT_RE.test(ext))) {
     tempPath = getFilepath(dir, base)
   }
   if (ext === '.md') {

test/cli.test.js

@@ -223,10 +223,15 @@ describe('cli', () => {
     )
   })
 
-  test('scripts with non standard extension (override)', async () => {
+  test('scripts with non standard extension', async () => {
     const o =
-      await $`node build/cli.js --ext-override test/fixtures/non-std-ext.zx`
+      await $`node build/cli.js --ext='.mjs' test/fixtures/non-std-ext.zx`
     assert.ok(o.stdout.trim().endsWith('zx/test/fixtures/non-std-ext.zx.mjs'))
+
+    await assert.rejects(
+      $`node build/cli.js test/fixtures/non-std-ext.zx`,
+      /Unknown file extension "\.zx"/
+    )
   })
 
   test22('scripts from stdin with explicit extension', async () => {

test/export.test.js

@@ -64,7 +64,6 @@ describe('cli', () => {
     assert.equal(typeof cli.argv, 'object', 'cli.argv')
     assert.equal(typeof cli.argv._, 'object', 'cli.argv._')
     assert.equal(typeof cli.argv.experimental, 'boolean', 'cli.argv.experimental')
-    assert.equal(typeof cli.argv.extOverride, 'boolean', 'cli.argv.extOverride')
     assert.equal(typeof cli.argv.h, 'boolean', 'cli.argv.h')
     assert.equal(typeof cli.argv.help, 'boolean', 'cli.argv.help')
     assert.equal(typeof cli.argv.i, 'boolean', 'cli.argv.i')