docs: describe CLI HLD - #1291
Merged
Merged
Conversation
antongolub
commented
Jul 29, 2025
Collaborator
- Tests pass
- Appropriate changes to README are included in PR
There was a problem hiding this comment.
Pull Request Overview
This PR adds documentation for the CLI component in the zx library's architecture guide, providing a high-level design overview of how the CLI processes and executes scripts.
- Adds a new CLI section to the architecture documentation
- Documents three key CLI helper functions and their responsibilities
- Includes a structured table describing the main components of the CLI workflow
| Consolidates error handling functionality across the zx library: errors codes mapping, formatting, stack parsing. | ||
|
|
||
| ## CLI | ||
| zx provides CLI with embedded script preprocessor to construct an execution context (apply presets, injects global vars) and to install the required deps. Then runs the specified script. |
There was a problem hiding this comment.
The sentence has a grammatical error. 'injects' should be 'inject' to maintain parallel structure with 'apply'.
Suggested change
| zx provides CLI with embedded script preprocessor to construct an execution context (apply presets, injects global vars) and to install the required deps. Then runs the specified script. | |
| zx provides CLI with embedded script preprocessor to construct an execution context (apply presets, inject global vars) and to install the required deps. Then runs the specified script. |
|
|
||
| | Helper | Description | | ||
| |----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| | `main()` | Inits a preset from flags, env vars and pushes the reader. | |
There was a problem hiding this comment.
'Inits' is not a proper word. It should be 'Initializes' for better documentation clarity.
Suggested change
| | `main()` | Inits a preset from flags, env vars and pushes the reader. | | |
| | `main()` | Initializes a preset from flags, env vars and pushes the reader. | |
| | Helper | Description | | ||
| |----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| | `main()` | Inits a preset from flags, env vars and pushes the reader. | | ||
| | `readScript()` | Fetches, parses and transforms the specified source into a runnable form. `stdin` reader, `https` loader and `md` transformer act right here. Deps analyzer internally relies on [depseek](https://www.npmjs.com/package/depseek) and inherits its limitations | |
There was a problem hiding this comment.
Missing comma after 'parses' for proper list formatting. It should be 'Fetches, parses, and transforms'.
Suggested change
| | `readScript()` | Fetches, parses and transforms the specified source into a runnable form. `stdin` reader, `https` loader and `md` transformer act right here. Deps analyzer internally relies on [depseek](https://www.npmjs.com/package/depseek) and inherits its limitations | | |
| | `readScript()` | Fetches, parses, and transforms the specified source into a runnable form. `stdin` reader, `https` loader and `md` transformer act right here. Deps analyzer internally relies on [depseek](https://www.npmjs.com/package/depseek) and inherits its limitations | |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.