chore(docs): initial commit (#204)

* chore(docs): initial commit

* feat(docs): poc for codegen

* docs: troubleshooting

* feat(docs): finish codegen

* fix: docs

* fix: diagnostics in docs

* fix: docs

* fix: docs

* fix: lint

* feat: integrate docs codegen into ci

* Update docs/codegen/src/utils.rs

Co-authored-by: Julian Domke <[email protected]>

* chore: merge main

* chore: lint fix

* chore: lint fix

---------

Co-authored-by: Julian Domke <[email protected]>

Author: psteinroe

.github/workflows/pull_request.yml

@@ -181,6 +181,8 @@ jobs:
         run: cargo run -p xtask_codegen -- analyser
       - name: Run the configuration codegen
         run: cargo run -p xtask_codegen -- configuration
+      - name: Run the docs codegen
+        run: cargo run -p docs_codegen
       - name: Check for git diff
         run: |
           if [[ $(git status --porcelain) ]]; then

Cargo.lock

@@ -1,5 +1,5 @@
 [workspace]
-members  = ["crates/*", "lib/*", "xtask/codegen", "xtask/rules_check"]
+members  = ["crates/*", "lib/*", "xtask/codegen", "xtask/rules_check", "docs/codegen"]
 resolver = "2"
 
 [workspace.package]
@@ -28,6 +28,7 @@ pg_query                 = "6.0.0"
 proc-macro2              = "1.0.66"
 quote                    = "1.0.33"
 rayon                    = "1.10.0"
+regex                    = "1.11.1"
 rustc-hash               = "2.0.0"
 schemars                 = { version = "0.8.21", features = ["indexmap2", "smallvec"] }
 serde                    = "1.0.195"
@@ -80,6 +81,8 @@ pglt_workspace              = { path = "./crates/pglt_workspace", version = "0.0
 
 pglt_test_macros = { path = "./crates/pglt_test_macros" }
 pglt_test_utils  = { path = "./crates/pglt_test_utils" }
-# parser = { path = "./crates/parser", version = "0.0.0" }
-# sql_parser = { path = "./crates/sql_parser", version = "0.0.0" }
-# sql_parser_codegen = { path = "./crates/sql_parser_codegen", version = "0.0.0" }
+
+docs_codegen = { path = "./docs/codegen", version = "0.0.0" }
+
+[profile.dev.package]
+insta.opt-level = 3

Cargo.toml

@@ -23,7 +23,7 @@ fn rule_test(full_path: &'static str, _: &str, _: &str) {
     };
 
     let query =
-        read_to_string(full_path).expect(format!("Failed to read file: {} ", full_path).as_str());
+        read_to_string(full_path).unwrap_or_else(|_| panic!("Failed to read file: {} ", full_path));
 
     let ast = pglt_query_ext::parse(&query).expect("failed to parse SQL");
     let options = AnalyserOptions::default();
@@ -51,7 +51,6 @@ fn rule_test(full_path: &'static str, _: &str, _: &str) {
 fn parse_test_path(path: &Path) -> (String, String, String) {
     let mut comps: Vec<&str> = path
         .components()
-        .into_iter()
         .map(|c| c.as_os_str().to_str().unwrap())
         .collect();
 

crates/pglt_analyser/tests/rules_tests.rs

@@ -48,7 +48,7 @@ pub struct CliOptions {
     #[bpaf(long("no-errors-on-unmatched"), switch)]
     pub no_errors_on_unmatched: bool,
 
-    /// Tell PGLSP to exit with an error code if some diagnostics emit warnings.
+    /// Tell PgLT to exit with an error code if some diagnostics emit warnings.
     #[bpaf(long("error-on-warnings"), switch)]
     pub error_on_warnings: bool,
 
@@ -86,7 +86,7 @@ pub struct CliOptions {
         fallback(Severity::default()),
         display_fallback
     )]
-    /// 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.
+    /// The level of diagnostics to show. In order, from the lowest to the most important: info, warn, error. Passing `--diagnostic-level=error` will cause PgLT to print only diagnostics that contain only errors.
     pub diagnostic_level: Severity,
 }
 

crates/pglt_cli/src/cli_options.rs

@@ -230,7 +230,7 @@ fn setup_tracing_subscriber(log_path: Option<PathBuf>, log_file_name_prefix: Opt
 }
 
 pub fn default_pglt_log_path() -> PathBuf {
-    match env::var_os("PGLSP_LOG_PATH") {
+    match env::var_os("PGLT_LOG_PATH") {
         Some(directory) => PathBuf::from(directory),
         None => pglt_fs::ensure_cache_dir().join("pglt-logs"),
     }

crates/pglt_cli/src/commands/daemon.rs

@@ -72,7 +72,7 @@ pub enum PgltCommand {
     Start {
         /// Allows to change the prefix applied to the file name of the logs.
         #[bpaf(
-            env("PGLSP_LOG_PREFIX_NAME"),
+            env("PGLT_LOG_PREFIX_NAME"),
             long("log-prefix-name"),
             argument("STRING"),
             hide_usage,
@@ -83,7 +83,7 @@ pub enum PgltCommand {
 
         /// Allows to change the folder where logs are stored.
         #[bpaf(
-            env("PGLSP_LOG_PATH"),
+            env("PGLT_LOG_PATH"),
             long("log-path"),
             argument("PATH"),
             hide_usage,
@@ -92,7 +92,7 @@ pub enum PgltCommand {
         log_path: PathBuf,
         /// Allows to set a custom file path to the configuration file,
         /// or a custom directory path to find `pglt.toml`
-        #[bpaf(env("PGLSP_LOG_PREFIX_NAME"), long("config-path"), argument("PATH"))]
+        #[bpaf(env("PGLT_LOG_PREFIX_NAME"), long("config-path"), argument("PATH"))]
         config_path: Option<PathBuf>,
     },
 
@@ -109,7 +109,7 @@ pub enum PgltCommand {
     LspProxy {
         /// Allows to change the prefix applied to the file name of the logs.
         #[bpaf(
-            env("PGLSP_LOG_PREFIX_NAME"),
+            env("PGLT_LOG_PREFIX_NAME"),
             long("log-prefix-name"),
             argument("STRING"),
             hide_usage,
@@ -119,7 +119,7 @@ pub enum PgltCommand {
         log_prefix_name: String,
         /// Allows to change the folder where logs are stored.
         #[bpaf(
-            env("PGLSP_LOG_PATH"),
+            env("PGLT_LOG_PATH"),
             long("log-path"),
             argument("PATH"),
             hide_usage,
@@ -128,7 +128,7 @@ pub enum PgltCommand {
         log_path: PathBuf,
         /// Allows to set a custom file path to the configuration file,
         /// or a custom directory path to find `pglt.toml`
-        #[bpaf(env("PGLSP_CONFIG_PATH"), long("config-path"), argument("PATH"))]
+        #[bpaf(env("PGLT_CONFIG_PATH"), long("config-path"), argument("PATH"))]
         config_path: Option<PathBuf>,
         /// Bogus argument to make the command work with vscode-languageclient
         #[bpaf(long("stdio"), hide, hide_usage, switch)]
@@ -143,7 +143,7 @@ pub enum PgltCommand {
     RunServer {
         /// Allows to change the prefix applied to the file name of the logs.
         #[bpaf(
-            env("PGLSP_LOG_PREFIX_NAME"),
+            env("PGLT_LOG_PREFIX_NAME"),
             long("log-prefix-name"),
             argument("STRING"),
             hide_usage,
@@ -153,7 +153,7 @@ pub enum PgltCommand {
         log_prefix_name: String,
         /// Allows to change the folder where logs are stored.
         #[bpaf(
-            env("PGLSP_LOG_PATH"),
+            env("PGLT_LOG_PATH"),
             long("log-path"),
             argument("PATH"),
             hide_usage,
@@ -165,7 +165,7 @@ pub enum PgltCommand {
         stop_on_disconnect: bool,
         /// Allows to set a custom file path to the configuration file,
         /// or a custom directory path to find `pglt.toml`
-        #[bpaf(env("PGLSP_CONFIG_PATH"), long("config-path"), argument("PATH"))]
+        #[bpaf(env("PGLT_CONFIG_PATH"), long("config-path"), argument("PATH"))]
         config_path: Option<PathBuf>,
     },
     #[bpaf(command("__print_socket"), hide)]

crates/pglt_cli/src/commands/mod.rs

@@ -15,7 +15,7 @@ fn command_name() -> String {
         .unwrap_or_else(|| String::from("pglt"))
 }
 
-/// A diagnostic that is emitted when running PGLSP via CLI.
+/// A diagnostic that is emitted when running PgLT via CLI.
 ///
 /// When displaying the diagnostic,
 #[derive(Debug, Diagnostic)]

crates/pglt_cli/src/diagnostics.rs

@@ -32,7 +32,7 @@ pub use panic::setup_panic_handler;
 pub use reporter::{DiagnosticsPayload, Reporter, ReporterVisitor, TraversalSummary};
 pub use service::{open_transport, SocketTransport};
 
-pub(crate) const VERSION: &str = match option_env!("PGLSP_VERSION") {
+pub(crate) const VERSION: &str = match option_env!("PGLT_VERSION") {
     Some(version) => version,
     None => env!("CARGO_PKG_VERSION"),
 };

crates/pglt_cli/src/lib.rs

@@ -46,7 +46,7 @@ impl std::str::FromStr for RuleGroup {
 #[cfg_attr(feature = "schema", derive(JsonSchema))]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 pub struct Rules {
-    #[doc = r" It enables the lint rules recommended by PGLSP. `true` by default."]
+    #[doc = r" It enables the lint rules recommended by PgLT. `true` by default."]
     #[serde(skip_serializing_if = "Option::is_none")]
     pub recommended: Option<bool>,
     #[doc = r" It enables ALL rules. The rules that belong to `nursery` won't be enabled."]

crates/pglt_configuration/src/analyser/linter/rules.rs

@@ -34,7 +34,7 @@ use migrations::{
 use serde::{Deserialize, Serialize};
 use vcs::VcsClientKind;
 
-pub const VERSION: &str = match option_env!("PGLSP_VERSION") {
+pub const VERSION: &str = match option_env!("PGLT_VERSION") {
     Some(version) => version,
     None => "0.0.0",
 };

crates/pglt_configuration/src/lib.rs

@@ -8,33 +8,33 @@ use std::sync::{LazyLock, OnceLock};
 
 /// Returns `true` if this is an unstable build of PgLT
 pub fn is_unstable() -> bool {
-    PGLSP_VERSION.deref().is_none()
+    PGLT_VERSION.deref().is_none()
 }
 
 /// The internal version of PgLT. This is usually supplied during the CI build
-pub static PGLSP_VERSION: LazyLock<Option<&str>> = LazyLock::new(|| option_env!("PGLSP_VERSION"));
+pub static PGLT_VERSION: LazyLock<Option<&str>> = LazyLock::new(|| option_env!("PGLT_VERSION"));
 
 pub struct PgLTEnv {
     pub pglt_log_path: PgLTEnvVariable,
     pub pglt_log_prefix: PgLTEnvVariable,
     pub pglt_config_path: PgLTEnvVariable,
 }
 
-pub static PGLSP_ENV: OnceLock<PgLTEnv> = OnceLock::new();
+pub static PGLT_ENV: OnceLock<PgLTEnv> = OnceLock::new();
 
 impl PgLTEnv {
     fn new() -> Self {
         Self {
             pglt_log_path: PgLTEnvVariable::new(
-                "PGLSP_LOG_PATH",
+                "PGLT_LOG_PATH",
                 "The directory where the Daemon logs will be saved.",
             ),
             pglt_log_prefix: PgLTEnvVariable::new(
-                "PGLSP_LOG_PREFIX_NAME",
+                "PGLT_LOG_PREFIX_NAME",
                 "A prefix that's added to the name of the log. Default: `server.log.`",
             ),
             pglt_config_path: PgLTEnvVariable::new(
-                "PGLSP_CONFIG_PATH",
+                "PGLT_CONFIG_PATH",
                 "A path to the configuration file",
             ),
         }
@@ -71,7 +71,7 @@ impl PgLTEnvVariable {
 }
 
 pub fn pglt_env() -> &'static PgLTEnv {
-    PGLSP_ENV.get_or_init(PgLTEnv::new)
+    PGLT_ENV.get_or_init(PgLTEnv::new)
 }
 
 impl Display for PgLTEnv {

crates/pglt_flags/src/lib.rs

@@ -18,14 +18,14 @@ mod os;
 pub struct ConfigName;
 
 impl ConfigName {
-    const PGLSP_TOML: [&'static str; 1] = ["pglt.toml"];
+    const PGLT_TOML: [&'static str; 1] = ["pglt.toml"];
 
     pub const fn pglt_toml() -> &'static str {
-        Self::PGLSP_TOML[0]
+        Self::PGLT_TOML[0]
     }
 
     pub const fn file_names() -> [&'static str; 1] {
-        Self::PGLSP_TOML
+        Self::PGLT_TOML
     }
 }
 

crates/pglt_fs/src/fs.rs

@@ -91,7 +91,7 @@ impl From<FileKind> for FileKinds {
 )]
 pub struct PgLTPath {
     path: PathBuf,
-    /// Determines the kind of the file inside PGLSP. Some files are considered as configuration files, others as manifest files, and others as files to handle
+    /// Determines the kind of the file inside PgLT. Some files are considered as configuration files, others as manifest files, and others as files to handle
     kind: FileKinds,
     /// Whether this path (usually a file) was fixed as a result of a format/lint/check command with the `--write` filag.
     was_written: bool,
@@ -164,7 +164,7 @@ impl PgLTPath {
     /// Returns the contents of a file, if it exists
     ///
     /// ## Error
-    /// If PGLSP doesn't have permissions to read the file
+    /// If PgLT doesn't have permissions to read the file
     pub fn get_buffer_from_file(&mut self) -> String {
         // we assume we have permissions
         read_to_string(&self.path).expect("cannot read the file to format")

crates/pglt_fs/src/path.rs

@@ -111,7 +111,7 @@ impl WorkspaceServer {
     /// Check whether a file is ignored in the top-level config `files.ignore`/`files.include`
     fn is_ignored(&self, path: &Path) -> bool {
         let file_name = path.file_name().and_then(|s| s.to_str());
-        // Never ignore PGLSP's config file regardless `include`/`ignore`
+        // Never ignore PgLT's config file regardless `include`/`ignore`
         (file_name != Some(ConfigName::pglt_toml())) &&
             // Apply top-level `include`/`ignore
             (self.is_ignored_by_top_level_config(path) || self.is_ignored_by_migration_config(path))
@@ -130,7 +130,7 @@ impl WorkspaceServer {
                 // `matched_path_or_any_parents` panics if `source` is not under the gitignore root.
                 // This checks excludes absolute paths that are not a prefix of the base root.
                 if !path.has_root() || path.starts_with(ignore.path()) {
-                    // Because PGLSP passes a list of paths,
+                    // Because PgLT passes a list of paths,
                     // we use `matched_path_or_any_parents` instead of `matched`.
                     ignore
                         .matched_path_or_any_parents(path, path.is_dir())