feat: add project preview command

[volodymyr-rutskyi]

What/Why/How?

Add a preview command that allows to run a preview of Redocly projects.
The command can accept the product to use for preview as an argument, deduce it fro the project's package.json, or use Realm by default.

The product package is executed via NPX.

The supported products are:

• Redoc: @redocly/redoc
• Revel: @redocly/revel
• Reef: @redocly/reef
• Realm: @redocly/realm
• Redoc + Revel: @redocly/redoc-revel
• Redoc + Reef: @redocly/redoc-reef
• Revel + Reef: @redocly/revel-reef

Reference

Docs PR: #1384

Testing

Screenshots (optional)

Check yourself

• Code is linted
• Tested with redoc/reference-docs/workflows (internal)
• All new/updated code is covered with tests

Security

• Security impact of change has been considered
• Code follows company security practices and guidelines

[changeset-bot]

⚠️ No Changeset found

Latest commit: a26c262

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

Command	Mean [s]	Min [s]	Max [s]	Relative
redocly lint packages/core/src/benchmark/benches/rebilly.yaml	1.060 ± 0.049	1.021	1.195	1.01 ± 0.05
redocly-next lint packages/core/src/benchmark/benches/rebilly.yaml	1.053 ± 0.023	1.015	1.083	1.00

[github-actions]

Coverage report

St.❔	Category	Percentage	Covered / Total
🟡	Statements	75.8%	4100/5409
🟡	Branches	66.09%	2183/3303
🟡	Functions	68.14%	663/973
🟡	Lines	76%	3847/5062

Show new covered files 🐣

St.❔	File	Statements	Branches	Functions	Lines
🔴	... / constants.ts	0%	100%	100%	0%
🔴	... / index.ts	0%	0%	0%	0%

Test suite run success

671 tests passing in 94 suites.

Report generated by 🧪jest coverage report action from a26c262

[tatomyr]

This looks good. However, the solution seems to be fragile. I'm afraid of the future situation when a user has an older version of Redocly CLI with one config structure, and the preview command pulls the latest version of Realm with a different config schema. Am I getting that right? Can we avoid the situation somehow?

[lornajane]

If the user has the other package dependency installed, could that package be used instead of npx? I'm thinking of how we evolve changes that affect both packages, and how users can pin versions if they need to (either for software dependency process reasons, or because they aren't ready to accept a change in our newer releases).

I'm not sure if the errors are coming through to the CLI correctly. If you supply a directory that is not a directory, it says it's launching the preview and then exits.

[lornajane]

A few comments on the command design:

• The project directory argument is strange, could we use --sourceDir instead, or something else?
• Is the directory required? It looks like it's not, but then the default (the current directory I think) should be included in the help output.
• What's the default value for the optional product parameter? (I think realm? Let's just add it to the help output)
• Please expand the command description to say what it does, it's too terse IMO.

I don't see any documentation for the preview command, but it should be included with the pull request, especially given the confusing naming with our existing preview-docs command, and explanations added to both pages. We'll also need to add some information about how the preview command is run since it's different to our other commands.

[volodymyr-rutskyi]

@lornajane thank you for the extensive feedback!

If the user has the other package dependency installed, could that package be used instead of npx? I'm thinking of how we evolve changes that affect both packages, and how users can pin versions if they need to (either for software dependency process reasons, or because they aren't ready to accept a change in our newer releases).

If the user has one of the product packages in package.json, then that package will be used. Then, if the user has a specific version in node_modules, NPX will launch that version.

However, if the user specifies the product argument, that product's package will be used ignoring what's in package.json (version from `node_modules will still be used if available).

---

I'm not sure if the errors are coming through to the CLI correctly. If you supply a directory that is not a directory, it says it's launching the preview and then exits.

The CLI preview command only serves as an interface for launching previews using product NPM packages, all of the output from those packages is shown and the console is also interactive. The behavior you described seems to be the fault of the packages that are being launched and should be fixed on that side. I will look into that.

---

I don't see any documentation for the preview command, but it should be included with the pull request, especially given the confusing naming with our existing preview-docs command, and explanations added to both pages. We'll also need to add some information about how the preview command is run since it's different to our other commands.

I was told that the docs should come in a separate PR because the docs are published right after PR merge and the CLI changes go through a different release process. I have the docs as a WIP and will open a PR and link it to this one later today or on Monday morning.

---

What's the default value for the optional product parameter? (I think realm? Let's just add it to the help output)

By default if the argument is not specified it tries to find a package.json file in the project directory and see if one of the packages is present there. If not, it defaults to realm. That info will be in the docs and I'll try to make it clearer in the help output.

[volodymyr-rutskyi]

This looks good. However, the solution seems to be fragile. I'm afraid of the future situation when a user has an older version of Redocly CLI with one config structure, and the preview command pulls the latest version of Realm with a different config schema. Am I getting that right? Can we avoid the situation somehow?

This should not be a problem. The preview does not rely on Redocly CLI for config. Right now, product NPM packages handle config schema by themselves and in the future they might handle config using the core package pinned in their dependencies, but should not rely on the CLI that launches them.

[volodymyr-rutskyi]

Adjusted some naming and descriptions and linked a PR with documentation for the command.
@lornajane