feat: load runtime diagnostic catalogs

This commit is contained in:
Dandaedre 2026-09-30 00:59:26 +02:00
parent 62a64ad816
commit 70ad6e5cf8
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
4 changed files with 206 additions and 9 deletions

View File

@ -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/<config_name>.toml` when a
4. named user config at `$XDG_CONFIG_HOME/john_slop/<config_name>.toml` when a
validated config name is selected;
4. an explicit `--config <path>` file;
5. explicit CLI flags for the current invocation.
5. an explicit `--config <path>` 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

View File

@ -149,6 +149,7 @@ impl ThresholdOverrides {
#[derive(Debug, Clone)]
pub struct ConfigLoader {
paths: ConfigPaths,
diagnostic_files: Vec<PathBuf>,
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<Item = PathBuf>) -> 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<Config, ConfigError> {
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::<DiagnosticCatalogLayer>()
.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<RulePatch>,
}
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct DiagnosticCatalogLayer {
schema_version: u32,
#[serde(default)]
rules: Vec<RulePatch>,
}
#[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();

View File

@ -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 `<config_name>.toml`;
4. an explicit `--config <FILE>`;
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 `<config_name>.toml`;
5. an explicit `--config <FILE>`;
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

View File

@ -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.