docs: separate rationale

Author: egasimus

README.md

@@ -33,13 +33,16 @@ Now you can publish your library with `npm run ubik publish`.
 
 ### Fixing extensions
 
-The recommended way to do this is by publishing your package with:
+`tsc` outputs invalid JavaScript when building ESM libraries. [Read more](./docs/extensions.md)
+
+The recommended way to fix this with Ubik is by using the following command
+instead of `npm publish` to publish your package to NPM:
 
 ```sh
 npm run ubik publish
 ```
 
-You can also do:
+You can also do this to apply the fix in place:
 
 ```sh
 npm run ubik compile
@@ -54,7 +57,12 @@ For best experience, add to `tsconfig.json`:
 {
   "exclude": [
     "dist/**/*"
-  ]
+  ],
+  "compilerOptions": {
+    "target": "esnext",
+    "module": "esnext",
+    "moduleResolution": "node10"
+  }
 }
 ```
 
@@ -69,39 +77,12 @@ dist/
 *.dist.d.ts
 ```
 
-This assumes that the entrypoint of your package (`main` in `package.json`)
+**KNOWN ISSUE:** This operation assumes that the entrypoint of your package (`main` in `package.json`)
 is at the top level of your source code tree, e.g. `./index.ts` or `./src/index.ts` -
 but not e.g. `./src/foo/index.ts` next to `./src/bar/somethingelse.ts` (the latter
 would probably fail to compile all files or will place them in inappropriate locations -
 good matter for a pull request.)
 
-#### Fixing extensions - rationale
-
-TypeScript wants you to import modules with:
-
-```ts
-import { foo } from "./foo"
-```
-
-but the ECMAScript specification expects:
-
-```js
-import { foo } from "./foo.js"
-```
-
-TypeScript doesn't add the extensions; it also doesn't provide an extensibility hook
-which could be used to add them. [The documentation](https://www.typescriptlang.org/docs/handbook/esm-node.html)
-is confusing and unhelpful; the solution that it suggests is ridiculous and unacceptable.
-On GitHub issues, the TypeScript developers have repeatedly reacted with indifference.
-
-**Before Node.js 16, this was less of a problem:** imports without extensions still
-worked. However, since Node 16 started enforcing the ES Modules spec (which requires
-extensions), the code that `tsc` outputs became effectively **invalid and impossible to run**
-(unless you were writing your program in a single file).
-
-What, were you expecting the compiler for evertone's favorite "strict superset of JS"
-to, idk, output correct JS that is ready to execute? You crazy person!
-
 ### Splitting away type imports
 
 ```sh
@@ -110,8 +91,13 @@ to, idk, output correct JS that is ready to execute? You crazy person!
 
 ### Fixing CommonJS star imports
 
+When targeting ESM on Node, CommonJS imports are wrapped in an extra `default` key,
+of which TypeScript is unaware. [Read more](./docs/split-stars.md)
+
+Let's rewrite the imports so that both work:
+
 ```sh
-// TODO
+npm exec ubik split-stars ./src -- protobufjs
 ```
 
 ### Others

docs/extensions.md

@@ -0,0 +1,24 @@
+TypeScript wants you to import modules with:
+
+```ts
+import { foo } from "./foo"
+```
+
+but the ECMAScript specification expects:
+
+```js
+import { foo } from "./foo.js"
+```
+
+TypeScript doesn't add the extensions; it also doesn't provide an extensibility hook
+which could be used to add them. [The documentation](https://www.typescriptlang.org/docs/handbook/esm-node.html)
+is confusing and unhelpful; the solution that it suggests is ridiculous and unacceptable.
+On GitHub issues, the TypeScript developers have repeatedly reacted with indifference.
+
+**Before Node.js 16, this was less of a problem:** imports without extensions still
+worked. However, since Node 16 started enforcing the ES Modules spec (which requires
+extensions), the code that `tsc` outputs became effectively **invalid and impossible to run**
+(unless you were writing your program in a single file).
+
+What, were you expecting the compiler for evertone's favorite "strict superset of JS"
+to, idk, output correct JS that is ready to execute? You crazy person!

docs/split-stars.md

@@ -0,0 +1,10 @@
+This compatibility issue was discovered when trying to port a Protobuf.js-based API client
+to import maps.
+
+As of 2023-09-27, Protobuf is a CommonJS-based library. Polyfilling it in the
+browser is perfectly doable. However, the generated protobuf bindings (what I assume
+the files importing starting with `import * as _m0` to be) are not completely valid
+when targeting ESM on Node, because Node adds an extra `default` key around the library
+when importing CJS from ESM, of which TypeScript is blissfully unaware.
+
+That ends up in a situation where you have either working code, or working types. Great!

ubik.cli.mjs

@@ -74,7 +74,7 @@ try {
 
     case 'split-stars': {
       if (argv.length === 0) {
-        console.error('You did not provide any inputs.')
+        console.error('You did not provide any arguments.')
         process.exit(1)
       }
       const split = argv.indexOf('--')
@@ -83,11 +83,11 @@ try {
         process.exit(1)
       }
       const pkgs = argv.slice(0, split)
-      const srcs = argv.slice(split + 1)
       if (pkgs.length < 1) {
-        console.error('You did not provide any packages imports of which to fix.')
+        console.error('You did not provide any packages.')
         process.exit(1)
       }
+      const srcs = argv.slice(split + 1)
       if (srcs.length < 1) {
         console.error('You did not provide any sources to process.')
         process.exit(1)
@@ -204,7 +204,7 @@ function printUsage () {
   console.info('     Provide more detailed descriptions of what each command does and why.')
   console.info(' ', bold('split-types'), '[--dry] [subdirs...]')
   console.info(`     ${colors.yellow('Experimental.')} Fix types imported without "import type"`)
-  console.info(' ', bold('split-stars'), '[--dry] packages... -- sources...')
+  console.info(' ', bold('split-stars'), '[--dry] packagenames... -- sourcedirs...')
   console.info(`     ${colors.yellow('Experimental.')} Fix default imports of CommonJS modules imported as ESM by Node`)
   console.info(' ', bold('fix-import-dirs'), '[--dry] [subdirs...]')
   console.info(`     ${colors.yellow('Experimental.')} Add missing directory indices`)
@@ -242,7 +242,7 @@ function printRationale () {
   console.info('     separate "import type" or "export type ... from" declarations.')
   console.info('     This way, TypeScript strips them at compile time and your code can run.')
   console.info()
-  console.info(' ', bold('split-stars'), '[--dry] packages... -- sources...')
+  console.info(' ', bold('split-stars'), '[--dry] packagenames... -- sourcedirs...')
   console.info()
   console.info('     In Node.js, when a ESM package imports a CommonJS package using "import *"')
   console.info('     an extra "default" key may be added around the imported package contents.')