Gradually deprecate running swift-format without input paths; require '-' for stdin in the future

[TTOzzi]

As discussed in #871 and in this forum thread Default behavior of “swift format”, waiting for stdin when only the swift format command is entered causes significant confusion for new users.
Although there were suggestions to provide a default behavior for convenience, I agree that it is not appropriate for a destructive change to take effect immediately.

However, at the very least, some guidance is needed to prevent the command from being perceived as hanging, so I've improved usability to output additional guidance when the user enters the swift format command alone.(same in swift format lint).

[allevato]

This would remove the ability to format/lint from stdin without also passing --assume-filename, which could be a breaking change in some workflows.

Before breaking any of the current usage patterns, at a minimum I think we need to start allowing - to be specified as a path that represents stdin and give users time to migrate to that. If someone uses swift-format (lint) without any path arguments, we could emit a warning that says something to the effect of running swift-format with no input paths is deprecated and will be removed in the future; specify '-' to use stdin but otherwise keep the current behavior for a release.

Then, after that release, we should revisit all of the default behaviors discussed in that thread holistically, so that we don't risk ending up in an intermediate stage if we were to make them arbitrarily or piecemeal.

[TTOzzi]

This would remove the ability to format/lint from stdin without also passing --assume-filename, which could be a breaking change in some workflows.

Before breaking any of the current usage patterns, at a minimum I think we need to start allowing - to be specified as a path that represents stdin and give users time to migrate to that. If someone uses swift-format (lint) without any path arguments, we could emit a warning that says something to the effect of running swift-format with no input paths is deprecated and will be removed in the future; specify '-' to use stdin but otherwise keep the current behavior for a release.

Then, after that release, we should revisit all of the default behaviors discussed in that thread holistically, so that we don't risk ending up in an intermediate stage if we were to make them arbitrarily or piecemeal.

Oh, I missed that it's possible to format/lint without the --assume-filename option. I modified the implementation so that it works correctly when code is provided via stdin.
Regarding this approach, I used isatty to check if there is input from the terminal for the swift-format command. Since I couldn't test it on Windows, I kept the existing behavior. However, I believe this improvement for Linux and macOS will be helpful.
I would appreciate your thoughts on this approach.
(I think this is also a temporary measure until we revisit the discussions regarding the default behaviors.)

[ahoppen]

I prefer @allevato’s proposal to use - as an input file name to indicate that the input is read from stdin instead of checking using atty because:

• There is wide precedence on other command line tools to indicate - as stdin
• I don’t think that piping a source file to swift-format is widely used, so the requiring user’s to add - to their invocation isn’t unreasonable
• The approach works on all platforms including Windows and is more explicit.

[DaveEwing]

• I don’t think that piping a source file to swift-format is widely used, so the requiring user’s to add - to their invocation isn’t unreasonable

IDEs probably do this. Xcode does. So they will have to update to support this change.

[ahoppen]

IDEs probably do this. Xcode does. So they will have to update to support this change.

It think it’s not unreasonable to ask these clients to update. In only expect there to be a handful.

[TTOzzi]

Thank you all for taking the time to share your thoughts 🙇
I have incorporated your feedback.

[allevato]

Suggested change

	@Argument(help: "Zero or more input filenames. If no paths are provided, stdin input will be used (use `-`).")
	@Argument(help: "Zero or more input filenames. Use `-` for stdin.")

No reason to explicitly document the "no paths" behavior if we're planning to deprecate it in the future; let's just document the happy path.

[allevato]

Suggested change

	Running swift-format without input paths is deprecated and will be removed in the future.
	Please specify one of the following:
	- Use - to read from stdin (e.g., cat MyFile.swift | swift-format -)
	- Provide a directory path (e.g., swift format --recursive MyDirectory/)
	- Provide a specific Swift source file (e.g., swift format MyFile.swift)
	For more information, use the --help option.
	Running swift-format without input paths is deprecated and will be removed in the future.
	Please update your invocation to do either of the following:
	- Pass `-` to read from stdin (e.g., `cat MyFile.swift | swift-format -`).
	- Pass one or more paths to Swift source files or directories containing
	Swift source files. When passing directories, make sure to include the
	`--recursive` flag.
	For more information, use the `--help` option.

Just a little editorial cleanup.

[TTOzzi]

Thank you for your feedback!

[allevato]

Thanks for working on this! I know it's a lot smaller in scope than what you were originally looking to do, but staging this in gently will be important for our users.