Changes to --dir, --cwd, --script-mode, add configSearchPath

[cspotcode]

@blakeembrey Do you have time to offer a sanity-check on these breaking changes? You might have some helpful historical perspective that I don't. I suspect that ts-node's current behavior is an understandable result of organic evolution over time, but we can make some changes to keep it clean and intuitive.

While working on #1155 I realized that --dir and --script-mode have some interesting behaviors. --dir is documented to change the location of config file resolution, but it actually does much more: it overrides process.cwd(). As far as I know, this affects TS_NODE_SCOPE and --project in a confusing way. For example, ts-node-script ./src/bin/main.ts will set cwd to ./src/bin, affecting the interpretation of --scope and --project, and affecting relative paths logged in error messages. A user would be confused by that.

With that in mind, do the following changes sound reasonable?

Proposed Changes

• rename --dir to --cwd so behavior is more intuitive. Keep --dir as deprecated for backwards compat.
• Rewrite --cwd docs to state that it overrides the cwd, which affects lots of things (can copy phrasing from git -C docs)
• [BREAKING] update --script-mode so that it affects tsconfig discovery but not cwd. Can accomplish via a new configSearchPath API option.

Questions

• Is configSearchPath a good name? configSearchDir?
• Should configSearchPath be exposed as a CLI flag / env var? I say no

[blakeembrey]

Pretty sure this is just my fault and no explicit reasoning, seemed logical at the time to have them affect everything because it's acting as if you were in that directory. IIRC the config flag was originally called --cwd but I renamed it at some point. I'm not sure how used --scope is in the real world, it was a workaround to allow multiple ts-node instances to be registered (e.g. allows ts-node to be registered from a node module which we've historically disallowed as a global automatic behavior).

I think the error paths might have been a mistake, didn't think through that one. I suspect it should have always used process.cwd() in that case, separate from the --dir flag. For --dir and --scope, I'd just want to make sure we can keep the linked package use-case alive (allow multiple ts-node instances to be registered for different paths). In that case, it makes a little less sense to think of it as a --cwd flag.

With the proposed change, would it help to write out how these things affect each other? I think when it comes to --dir, --scope and --script-mode there's some odd combos I never expect to see - specifically --scope and --script-mode. When you mention "so that it affects tsconfig discovery but not cwd" I'm assuming you're talking about how much --dir affects today? I agree with that, that'd be a first step that de-couples --dir and --script-mode.

Question: do you think --script-mode should affect --dir as it relates to --scope? Is there any other --dir behaviors we're missing?

Is configSearchPath a good name?

SGTM.

Should configSearchPath be exposed as a CLI flag / env var? I say no

Also seems reasonable to start with it internal only.

[cspotcode]

Ok, thanks, good idea to enumerate all sensible and non-sensible combinations of flags. Also, it's possible I've subtly broken --dir's behavior over time, as I changed surrounding code.

Question: do you think --script-mode should affect --dir as it relates to --scope? Is there any other --dir behaviors we're missing?

It seems most useful for --dir to default to either a) directory containing tsconfig.json or b) rootDir according to tsconfig.json

When you mention "so that it affects tsconfig discovery but not cwd" I'm assuming you're talking about how much --dir affects today?

Now I'm thinking --dir's only effect should be setting the directory for --scope. Everything else can be driven by --project, projectSearchPath, --script-mode, and (rarely) --cwd.

Use-cases

categorized as either useful to CLI consumers, API consumers, or both

• CLI: from shebang, find tsconfig.json corresponding to entry-point file: --script-mode
• CLI&API: specify tsconfig explicitly: --project / project
• CLI&API: scope compiler to a single TS project, so multiples can be registered in one process: --scope/scope and --scopeDir/scopeDir
• API: search for tsconfig, avoiding error-prone custom findUp logic: projectSearchPath

Less common use-cases

• CLI&API: override effective CWD: --cwd / cwd

---

Permutations

The messiest conceivable combinations, with all flags being optional:

• --cwd, --scope, --scopeDir, and --script-mode (and via API)
• --cwd, --scope, --scopeDir, and --cwd-mode (if added by [BREAKING] make --script-mode the default; add --cwd-mode to switch back to old behavior #1155) (and via API)
• --cwd, --scope, --scopeDir, and --project (and via API)
• cwd, scope, scopeDir, and projectSearchPath (only via API, not CLI)

In all cases, --scopeDir defaults to the directory containing the tsconfig file.

Questions

• Should --dir be renamed to --scopeDir?
• Should --scopeDir default to the directory containing the config file? Or should it default to rootDir, which is more complex, but maybe more correct?
• How does renaming to projectSearchPath sound? It'll match the project option.
• Should we collapse scope and scopeDir into a single option?