Skip to content

Commit 9c200d4

Browse files
psteinroepsteinroe
committed
feat(docs): poc for codegen
1 parent 7ed42b6 commit 9c200d4

File tree

12 files changed

+475
-4
lines changed

12 files changed

+475
-4
lines changed

‎Cargo.lock‎

Lines changed: 13 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎Cargo.toml‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
[workspace]
2-
members = ["crates/*", "lib/*", "xtask/codegen", "xtask/rules_check"]
2+
members = ["crates/*", "lib/*", "xtask/codegen", "xtask/rules_check", "docs/codegen"]
33
resolver = "2"
44

55
[workspace.package]
@@ -28,6 +28,7 @@ pg_query = "6.0.0"
2828
proc-macro2 = "1.0.66"
2929
quote = "1.0.33"
3030
rayon = "1.10.0"
31+
regex = "1.11.1"
3132
rustc-hash = "2.0.0"
3233
schemars = { version = "0.8.21", features = ["indexmap2", "smallvec"] }
3334
serde = "1.0.195"
@@ -79,10 +80,8 @@ pglt_typecheck = { path = "./crates/pglt_typecheck", version = "0.0
7980
pglt_workspace = { path = "./crates/pglt_workspace", version = "0.0.0" }
8081

8182
pglt_test_utils = { path = "./crates/pglt_test_utils" }
82-
# parser = { path = "./crates/parser", version = "0.0.0" }
83-
# sql_parser = { path = "./crates/sql_parser", version = "0.0.0" }
84-
# sql_parser_codegen = { path = "./crates/sql_parser_codegen", version = "0.0.0" }
8583

84+
docs_codegen = { path = "./docs/codegen", version = "0.0.0" }
8685

8786
[profile.dev.package]
8887
insta.opt-level = 3

‎docs/cli_reference.md‎

Lines changed: 289 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,289 @@
1+
## CLI Reference
2+
3+
[//]: # (BEGIN CLI_REF)
4+
5+
6+
7+
# Command summary
8+
9+
* [`pglt`↴](#pglt)
10+
* [`pglt version`↴](#pglt-version)
11+
* [`pglt check`↴](#pglt-check)
12+
* [`pglt start`↴](#pglt-start)
13+
* [`pglt stop`↴](#pglt-stop)
14+
* [`pglt init`↴](#pglt-init)
15+
* [`pglt lsp-proxy`↴](#pglt-lsp-proxy)
16+
* [`pglt clean`↴](#pglt-clean)
17+
18+
## pglt
19+
20+
PgLT official CLI. Use it to check the health of your project or run it to check single files.
21+
22+
**Usage**: **`pglt`** _`COMMAND ...`_
23+
24+
**Available options:**
25+
- **`-h`**, **`--help`** —
26+
Prints help information
27+
- **`-V`**, **`--version`** —
28+
Prints version information
29+
30+
31+
32+
**Available commands:**
33+
- **`version`** —
34+
Shows the version information and quit.
35+
- **`check`** —
36+
Runs everything to the requested files.
37+
- **`start`** —
38+
Starts the daemon server process.
39+
- **`stop`** —
40+
Stops the daemon server process.
41+
- **`init`** —
42+
Bootstraps a new project. Creates a configuration file with some defaults.
43+
- **`lsp-proxy`** —
44+
Acts as a server for the Language Server Protocol over stdin/stdout.
45+
- **`clean`** —
46+
Cleans the logs emitted by the daemon.
47+
48+
49+
## pglt version
50+
51+
Shows the version information and quit.
52+
53+
**Usage**: **`pglt`** **`version`**
54+
55+
**Global options applied to all commands**
56+
- **` --colors`**=_`<off|force>`_ &mdash;
57+
Set the formatting mode for markup: "off" prints everything as plain text, "force" forces the formatting of markup using ANSI even if the console output is determined to be incompatible
58+
- **` --use-server`** &mdash;
59+
Connect to a running instance of the daemon server.
60+
- **` --skip-db`** &mdash;
61+
Skip connecting to the database and only run checks that don't require a database connection.
62+
- **` --verbose`** &mdash;
63+
Print additional diagnostics, and some diagnostics show more information. Also, print out what files were processed and which ones were modified.
64+
- **` --config-path`**=_`PATH`_ &mdash;
65+
Set the file path to the configuration file, or the directory path to find `pglt.toml`. If used, it disables the default configuration file resolution.
66+
- **` --max-diagnostics`**=_`<none|<NUMBER>>`_ &mdash;
67+
Cap the amount of diagnostics displayed. When `none` is provided, the limit is lifted.
68+
69+
[default: 20]
70+
- **` --skip-errors`** &mdash;
71+
Skip over files containing syntax errors instead of emitting an error diagnostic.
72+
- **` --no-errors-on-unmatched`** &mdash;
73+
Silence errors that would be emitted in case no files were processed during the execution of the command.
74+
- **` --error-on-warnings`** &mdash;
75+
Tell PGLSP to exit with an error code if some diagnostics emit warnings.
76+
- **` --reporter`**=_`<json|json-pretty|github|junit|summary|gitlab>`_ &mdash;
77+
Allows to change how diagnostics and summary are reported.
78+
- **` --log-level`**=_`<none|debug|info|warn|error>`_ &mdash;
79+
The level of logging. In order, from the most verbose to the least verbose: debug, info, warn, error.
80+
81+
The value `none` won't show any logging.
82+
83+
[default: none]
84+
- **` --log-kind`**=_`<pretty|compact|json>`_ &mdash;
85+
How the log should look like.
86+
87+
[default: pretty]
88+
- **` --diagnostic-level`**=_`<info|warn|error>`_ &mdash;
89+
The level of diagnostics to show. In order, from the lowest to the most important: info, warn, error. Passing `--diagnostic-level=error` will cause PGLSP to print only diagnostics that contain only errors.
90+
91+
[default: info]
92+
93+
94+
95+
**Available options:**
96+
- **`-h`**, **`--help`** &mdash;
97+
Prints help information
98+
99+
100+
## pglt check
101+
102+
Runs everything to the requested files.
103+
104+
**Usage**: **`pglt`** **`check`** \[**`--staged`**\] \[**`--changed`**\] \[**`--since`**=_`REF`_\] \[_`PATH`_\]...
105+
106+
**The configuration that is contained inside the configuration file.**
107+
- **` --vcs-enabled`**=_`<true|false>`_ &mdash;
108+
Whether we should integrate itself with the VCS client
109+
- **` --vcs-client-kind`**=_`<git>`_ &mdash;
110+
The kind of client.
111+
- **` --vcs-use-ignore-file`**=_`<true|false>`_ &mdash;
112+
Whether we should use the VCS ignore file. When [true], we will ignore the files specified in the ignore file.
113+
- **` --vcs-root`**=_`PATH`_ &mdash;
114+
The folder where we should check for VCS files. By default, we will use the same folder where `pglt.toml` was found.
115+
116+
If we can't find the configuration, it will attempt to use the current working directory. If no current working directory can't be found, we won't use the VCS integration, and a diagnostic will be emitted
117+
- **` --vcs-default-branch`**=_`BRANCH`_ &mdash;
118+
The main branch of the project
119+
- **` --files-max-size`**=_`NUMBER`_ &mdash;
120+
The maximum allowed size for source code files in bytes. Files above this limit will be ignored for performance reasons. Defaults to 1 MiB
121+
- **` --migrations-dir`**=_`ARG`_ &mdash;
122+
The directory where the migration files are stored
123+
- **` --after`**=_`ARG`_ &mdash;
124+
Ignore any migrations before this timestamp
125+
- **` --host`**=_`ARG`_ &mdash;
126+
The host of the database.
127+
- **` --port`**=_`ARG`_ &mdash;
128+
The port of the database.
129+
- **` --username`**=_`ARG`_ &mdash;
130+
The username to connect to the database.
131+
- **` --password`**=_`ARG`_ &mdash;
132+
The password to connect to the database.
133+
- **` --database`**=_`ARG`_ &mdash;
134+
The name of the database.
135+
- **` --conn_timeout_secs`**=_`ARG`_ &mdash;
136+
The connection timeout in seconds.
137+
138+
[default: Some(10)]
139+
140+
141+
142+
**Global options applied to all commands**
143+
- **` --colors`**=_`<off|force>`_ &mdash;
144+
Set the formatting mode for markup: "off" prints everything as plain text, "force" forces the formatting of markup using ANSI even if the console output is determined to be incompatible
145+
- **` --use-server`** &mdash;
146+
Connect to a running instance of the daemon server.
147+
- **` --skip-db`** &mdash;
148+
Skip connecting to the database and only run checks that don't require a database connection.
149+
- **` --verbose`** &mdash;
150+
Print additional diagnostics, and some diagnostics show more information. Also, print out what files were processed and which ones were modified.
151+
- **` --config-path`**=_`PATH`_ &mdash;
152+
Set the file path to the configuration file, or the directory path to find `pglt.toml`. If used, it disables the default configuration file resolution.
153+
- **` --max-diagnostics`**=_`<none|<NUMBER>>`_ &mdash;
154+
Cap the amount of diagnostics displayed. When `none` is provided, the limit is lifted.
155+
156+
[default: 20]
157+
- **` --skip-errors`** &mdash;
158+
Skip over files containing syntax errors instead of emitting an error diagnostic.
159+
- **` --no-errors-on-unmatched`** &mdash;
160+
Silence errors that would be emitted in case no files were processed during the execution of the command.
161+
- **` --error-on-warnings`** &mdash;
162+
Tell PGLSP to exit with an error code if some diagnostics emit warnings.
163+
- **` --reporter`**=_`<json|json-pretty|github|junit|summary|gitlab>`_ &mdash;
164+
Allows to change how diagnostics and summary are reported.
165+
- **` --log-level`**=_`<none|debug|info|warn|error>`_ &mdash;
166+
The level of logging. In order, from the most verbose to the least verbose: debug, info, warn, error.
167+
168+
The value `none` won't show any logging.
169+
170+
[default: none]
171+
- **` --log-kind`**=_`<pretty|compact|json>`_ &mdash;
172+
How the log should look like.
173+
174+
[default: pretty]
175+
- **` --diagnostic-level`**=_`<info|warn|error>`_ &mdash;
176+
The level of diagnostics to show. In order, from the lowest to the most important: info, warn, error. Passing `--diagnostic-level=error` will cause PGLSP to print only diagnostics that contain only errors.
177+
178+
[default: info]
179+
180+
181+
182+
**Available positional items:**
183+
- _`PATH`_ &mdash;
184+
Single file, single path or list of paths
185+
186+
187+
188+
**Available options:**
189+
- **` --stdin-file-path`**=_`PATH`_ &mdash;
190+
Use this option when you want to format code piped from `stdin`, and print the output to `stdout`.
191+
192+
The file doesn't need to exist on disk, what matters is the extension of the file. Based on the extension, we know how to check the code.
193+
194+
Example: `echo 'let a;' | pglt_cli check --stdin-file-path=test.sql`
195+
- **` --staged`** &mdash;
196+
When set to true, only the files that have been staged (the ones prepared to be committed) will be linted. This option should be used when working locally.
197+
- **` --changed`** &mdash;
198+
When set to true, only the files that have been changed compared to your `defaultBranch` configuration will be linted. This option should be used in CI environments.
199+
- **` --since`**=_`REF`_ &mdash;
200+
Use this to specify the base branch to compare against when you're using the --changed flag and the `defaultBranch` is not set in your `pglt.toml`
201+
- **`-h`**, **`--help`** &mdash;
202+
Prints help information
203+
204+
205+
## pglt start
206+
207+
Starts the daemon server process.
208+
209+
**Usage**: **`pglt`** **`start`** \[**`--config-path`**=_`PATH`_\]
210+
211+
**Available options:**
212+
- **` --log-prefix-name`**=_`STRING`_ &mdash;
213+
Allows to change the prefix applied to the file name of the logs.
214+
215+
Uses environment variable **`PGLSP_LOG_PREFIX_NAME`**
216+
217+
[default: server.log]
218+
- **` --log-path`**=_`PATH`_ &mdash;
219+
Allows to change the folder where logs are stored.
220+
221+
Uses environment variable **`PGLSP_LOG_PATH`**
222+
- **` --config-path`**=_`PATH`_ &mdash;
223+
Allows to set a custom file path to the configuration file, or a custom directory path to find `pglt.toml`
224+
225+
Uses environment variable **`PGLSP_LOG_PREFIX_NAME`**
226+
- **`-h`**, **`--help`** &mdash;
227+
Prints help information
228+
229+
230+
## pglt stop
231+
232+
Stops the daemon server process.
233+
234+
**Usage**: **`pglt`** **`stop`**
235+
236+
**Available options:**
237+
- **`-h`**, **`--help`** &mdash;
238+
Prints help information
239+
240+
241+
## pglt init
242+
243+
Bootstraps a new project. Creates a configuration file with some defaults.
244+
245+
**Usage**: **`pglt`** **`init`**
246+
247+
**Available options:**
248+
- **`-h`**, **`--help`** &mdash;
249+
Prints help information
250+
251+
252+
## pglt lsp-proxy
253+
254+
Acts as a server for the Language Server Protocol over stdin/stdout.
255+
256+
**Usage**: **`pglt`** **`lsp-proxy`** \[**`--config-path`**=_`PATH`_\]
257+
258+
**Available options:**
259+
- **` --log-prefix-name`**=_`STRING`_ &mdash;
260+
Allows to change the prefix applied to the file name of the logs.
261+
262+
Uses environment variable **`PGLSP_LOG_PREFIX_NAME`**
263+
264+
[default: server.log]
265+
- **` --log-path`**=_`PATH`_ &mdash;
266+
Allows to change the folder where logs are stored.
267+
268+
Uses environment variable **`PGLSP_LOG_PATH`**
269+
- **` --config-path`**=_`PATH`_ &mdash;
270+
Allows to set a custom file path to the configuration file, or a custom directory path to find `pglt.toml`
271+
272+
Uses environment variable **`PGLSP_CONFIG_PATH`**
273+
- **`-h`**, **`--help`** &mdash;
274+
Prints help information
275+
276+
277+
## pglt clean
278+
279+
Cleans the logs emitted by the daemon.
280+
281+
**Usage**: **`pglt`** **`clean`**
282+
283+
**Available options:**
284+
- **`-h`**, **`--help`** &mdash;
285+
Prints help information
286+
287+
288+
289+
[//]: # (END CLI_REF)

‎docs/codegen/Cargo.toml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
2+
[package]
3+
authors.workspace = true
4+
categories.workspace = true
5+
description = "<DESCRIPTION>"
6+
edition.workspace = true
7+
homepage.workspace = true
8+
keywords.workspace = true
9+
license.workspace = true
10+
name = "docs_codegen"
11+
repository.workspace = true
12+
version = "0.0.0"
13+
14+
[dependencies]
15+
regex = { workspace = true }
16+
toml = { workspace = true }
17+
anyhow = { workspace = true }
18+
bpaf = { workspace = true, features = ["docgen"] }
19+
20+
pglt_configuration = { workspace = true }
21+
pglt_flags = { workspace = true }
22+
pglt_cli = { workspace = true }
23+

‎docs/codegen/src/cli_doc.rs‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
use pglt_cli::pglt_command;
2+
use std::{fs, path::Path};
3+
4+
use crate::utils;
5+
6+
pub fn generate_cli_doc(docs_dir: &Path) -> anyhow::Result<()> {
7+
let file_path = docs_dir.join("cli_reference.md");
8+
9+
let content = fs::read_to_string(&file_path)?;
10+
11+
let new_content =
12+
utils::replace_section(&content, "CLI_REF", &pglt_command().render_markdown("pglt"));
13+
14+
fs::write(file_path, &new_content)?;
15+
16+
Ok(())
17+
}

0 commit comments

Comments
 (0)