diff --git a/AGENTS.md b/AGENTS.md index f6de78b..f2dc334 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -146,12 +146,20 @@ The precedence from lowest to highest is: 1. embedded `crates/john-slop-core/assets/config.toml` and `crates/john-slop-core/assets/heuristics.toml`; -2. user base config at `$XDG_CONFIG_HOME/john_slop/config.toml`, conventionally +2. runtime diagnostic catalogs: the optional user-wide `diagnostics.toml`, then + explicitly selected catalogs in command-line order; +3. user base config at `$XDG_CONFIG_HOME/john_slop/config.toml`, conventionally `~/.config/john_slop/config.toml` on Linux; -3. named user config at `$XDG_CONFIG_HOME/john_slop/.toml` when a +4. named user config at `$XDG_CONFIG_HOME/john_slop/.toml` when a validated config name is selected; -4. an explicit `--config ` file; -5. explicit CLI flags for the current invocation. +5. an explicit `--config ` file; +6. explicit CLI flags for the current invocation. + +Diagnostic catalog files may contain only `schema_version` and `[[rules]]`. +They can add or patch data-driven rules but cannot define executable matcher +algorithms, categories, replacements, thresholds, or input policy. Normal +configuration layers intentionally load afterward so they can disable or tune +catalog rules by stable ID. Missing optional files are allowed; malformed files are fatal and identify their origin. A config name accepts only ASCII letters, digits, `_`, and `-`; it cannot diff --git a/crates/john-slop-core/src/config.rs b/crates/john-slop-core/src/config.rs index 8e0146f..8122f18 100644 --- a/crates/john-slop-core/src/config.rs +++ b/crates/john-slop-core/src/config.rs @@ -149,6 +149,7 @@ impl ThresholdOverrides { #[derive(Debug, Clone)] pub struct ConfigLoader { paths: ConfigPaths, + diagnostic_files: Vec, overrides: ConfigOverrides, } @@ -166,10 +167,17 @@ impl ConfigLoader { pub fn from_paths(paths: ConfigPaths) -> Self { Self { paths, + diagnostic_files: Vec::new(), overrides: ConfigOverrides::default(), } } + /// Add required runtime diagnostic catalogs in declaration order. + pub fn with_diagnostic_files(mut self, paths: impl IntoIterator) -> Self { + self.diagnostic_files.extend(paths); + self + } + /// Add highest-precedence scalar overrides from the current invocation. pub fn with_overrides(mut self, overrides: ConfigOverrides) -> Self { self.overrides = overrides; @@ -181,9 +189,21 @@ impl ConfigLoader { &self.paths } + /// Return explicitly selected runtime diagnostic catalogs in load order. + pub fn diagnostic_files(&self) -> &[PathBuf] { + &self.diagnostic_files + } + /// Load embedded, user, named, explicit, and command-line layers in order. pub fn load(&self) -> Result { let mut config = Config::embedded(); + apply_optional_diagnostic_file(&mut config, &self.paths.diagnostics())?; + for path in &self.diagnostic_files { + if !path.exists() { + return Err(ConfigError::ExplicitDiagnosticFileMissing { path: path.clone() }); + } + apply_diagnostic_file(&mut config, path)?; + } apply_optional_file(&mut config, &self.paths.base)?; if let Some(path) = &self.paths.named { apply_optional_file(&mut config, path)?; @@ -214,6 +234,22 @@ pub enum ConfigError { /// Requested explicit path. path: PathBuf, }, + /// A deliberately selected runtime diagnostic catalog does not exist. + #[error("explicit diagnostic catalog `{path}` does not exist")] + #[diagnostic(code(john_slop::config::diagnostics_missing))] + ExplicitDiagnosticFileMissing { + /// Requested diagnostic catalog path. + path: PathBuf, + }, + /// A runtime diagnostic catalog uses an unsupported schema. + #[error("diagnostic catalog `{path}` has schema_version {actual}; expected 1")] + #[diagnostic(code(john_slop::config::diagnostics_schema))] + UnsupportedDiagnosticSchema { + /// Diagnostic catalog path. + path: PathBuf, + /// Unsupported schema version. + actual: u32, + }, /// Figment could not read, parse, merge, or deserialize a source. #[error("failed to load embedded configuration")] #[diagnostic(code(john_slop::config::embedded_invalid))] @@ -430,6 +466,34 @@ fn apply_optional_file(config: &mut Config, path: &std::path::Path) -> Result<() } } +fn apply_optional_diagnostic_file( + config: &mut Config, + path: &std::path::Path, +) -> Result<(), ConfigError> { + if path.exists() { + apply_diagnostic_file(config, path) + } else { + Ok(()) + } +} + +fn apply_diagnostic_file(config: &mut Config, path: &std::path::Path) -> Result<(), ConfigError> { + let source_text = std::fs::read_to_string(path).map_err(|source| ConfigError::Read { + path: path.to_owned(), + source, + })?; + let catalog = Figment::from(Toml::string(&source_text)) + .extract::() + .map_err(|source| layer_error(path, source_text, source))?; + if catalog.schema_version != 1 { + return Err(ConfigError::UnsupportedDiagnosticSchema { + path: path.to_owned(), + actual: catalog.schema_version, + }); + } + merge_rules(&mut config.rules, catalog.rules, path) +} + fn apply_file(config: &mut Config, path: &std::path::Path) -> Result<(), ConfigError> { let source_text = std::fs::read_to_string(path).map_err(|source| ConfigError::Read { path: path.to_owned(), @@ -508,6 +572,14 @@ struct ConfigLayer { rules: Vec, } +#[derive(Debug, Deserialize)] +#[serde(deny_unknown_fields)] +struct DiagnosticCatalogLayer { + schema_version: u32, + #[serde(default)] + rules: Vec, +} + #[derive(Debug, Default, Deserialize)] #[serde(default, deny_unknown_fields)] struct DiagnosticLayer { @@ -781,6 +853,11 @@ impl ConfigPaths { Some(Self::in_directory(directory, name, explicit)) } + /// Return the optional user-wide runtime diagnostic catalog path. + pub fn diagnostics(&self) -> PathBuf { + self.directory.join("diagnostics.toml") + } + /// Resolve paths under a known directory, primarily for deterministic tests. pub fn in_directory( directory: PathBuf, @@ -1378,10 +1455,115 @@ mod tests { ); assert_eq!(paths.base, directory.join("config.toml")); + assert_eq!(paths.diagnostics(), directory.join("diagnostics.toml")); assert_eq!(paths.named, Some(directory.join("strict-mode.toml"))); assert_eq!(paths.explicit, Some(PathBuf::from("project.toml"))); } + #[test] + fn runtime_diagnostic_catalogs_load_before_normal_overrides() { + let directory = tempfile::tempdir().unwrap(); + let first = directory.path().join("first.toml"); + let second = directory.path().join("second.toml"); + std::fs::write( + directory.path().join("diagnostics.toml"), + r#" +schema_version = 1 + +[[rules]] +id = "custom-review-marker" +category = "style" +severity = "warning" +matcher = "exact-phrase" +pattern = "REVIEW BEFORE PUBLISHING" +weight = 8.0 +message = "a project review marker remains" +help = "Resolve or remove the marker before publishing." +occurrence_cap = 1 +enabled = true +scope = { content = ["prose", "source-code"], extensions = [] } +"#, + ) + .unwrap(); + std::fs::write( + &first, + "schema_version = 1\n[[rules]]\nid = \"custom-review-marker\"\nweight = 9.0\n", + ) + .unwrap(); + std::fs::write( + &second, + "schema_version = 1\n[[rules]]\nid = \"custom-review-marker\"\nweight = 10.0\n", + ) + .unwrap(); + std::fs::write( + directory.path().join("config.toml"), + "[[rules]]\nid = \"custom-review-marker\"\nenabled = false\nweight = 11.0\n", + ) + .unwrap(); + let paths = ConfigPaths::in_directory(directory.path().to_owned(), None, None); + + let config = ConfigLoader::from_paths(paths) + .with_diagnostic_files([first, second]) + .load() + .unwrap(); + let rule = config + .rules + .iter() + .find(|rule| rule.id == "custom-review-marker") + .unwrap(); + + assert!(!rule.enabled); + assert_eq!(rule.weight, 11.0); + assert_eq!(config.rules.len(), 13); + } + + #[test] + fn runtime_diagnostic_catalogs_reject_unsafe_shapes_and_missing_files() { + let directory = tempfile::tempdir().unwrap(); + let paths = ConfigPaths::in_directory(directory.path().to_owned(), None, None); + let missing = directory.path().join("missing.toml"); + let error = ConfigLoader::from_paths(paths.clone()) + .with_diagnostic_files([missing.clone()]) + .load() + .unwrap_err(); + assert!(matches!( + error, + ConfigError::ExplicitDiagnosticFileMissing { path } if path == missing + )); + + let catalog = directory.path().join("catalog.toml"); + std::fs::write(&catalog, "schema_version = 2\n").unwrap(); + let error = ConfigLoader::from_paths(paths.clone()) + .with_diagnostic_files([catalog.clone()]) + .load() + .unwrap_err(); + assert!(matches!( + error, + ConfigError::UnsupportedDiagnosticSchema { actual: 2, .. } + )); + + std::fs::write(&catalog, "schema_version = 1\n[thresholds]\nlow = 10\n").unwrap(); + let error = ConfigLoader::from_paths(paths.clone()) + .with_diagnostic_files([catalog.clone()]) + .load() + .unwrap_err(); + assert!(matches!(error, ConfigError::Layer(layer) if layer.path == catalog)); + + std::fs::write( + &catalog, + "schema_version = 1\n[[rules]]\nid = \"incomplete-rule\"\n", + ) + .unwrap(); + let error = ConfigLoader::from_paths(paths) + .with_diagnostic_files([catalog]) + .load() + .unwrap_err(); + assert!(matches!( + error, + ConfigError::IncompleteEntry { kind: "rule", .. } + )); + } + #[test] fn layered_scalar_precedence_is_deterministic() { let directory = tempfile::tempdir().unwrap(); diff --git a/docs/configuration.md b/docs/configuration.md index fa4e8fc..fd45e7c 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -9,10 +9,17 @@ default files. Configuration layers are applied from lowest to highest priority: 1. embedded `assets/config.toml` and `assets/heuristics.toml`; -2. the platform user file `config.toml`; -3. a selected user `.toml`; -4. an explicit `--config `; -5. configuration flags for the current invocation. +2. the optional platform user diagnostic catalog `diagnostics.toml`, followed + by explicitly selected diagnostic catalogs in declaration order; +3. the platform user file `config.toml`; +4. a selected user `.toml`; +5. an explicit `--config `; +6. configuration flags for the current invocation. + +Diagnostic catalogs load before normal configuration so a base, named, or +explicit configuration can tune or disable a catalog rule by stable ID. A +catalog accepts only `schema_version` and `[[rules]]`; unrelated settings are a +configuration error rather than being silently applied from the wrong file. On Linux, the user directory conventionally resolves to `~/.config/john_slop`. John Slop uses operating-system APIs rather than reading diff --git a/tasks.md b/tasks.md index 39c17ff..7ee26e0 100644 --- a/tasks.md +++ b/tasks.md @@ -608,7 +608,7 @@ metadata and binary versions agree on `0.1.23`. ## Milestone 24 — Runtime diagnostic catalogs -- [ ] Load a dedicated `$CONFIG_DIR/john_slop/diagnostics.toml` before normal +- [x] Load a dedicated `$CONFIG_DIR/john_slop/diagnostics.toml` before normal configuration overrides, and accept repeatable explicit diagnostic catalogs. Restrict these files to schema metadata and `[[rules]]`, retain merge-by-ID, reject malformed/incomplete/duplicate definitions, and test precedence.