From 177337c0aebe49a0ebba70856e8d519769bb61f8 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Tue, 29 Sep 2026 13:17:48 +0200 Subject: [PATCH] feat: embed typed heuristic catalog --- assets/heuristics.toml | 98 ++++++++++++++++++++++++++++++++++++++++ src/config.rs | 100 ++++++++++++++++++++++++++++++++++++++++- src/lib.rs | 5 ++- src/model.rs | 5 ++- tasks.md | 2 +- 5 files changed, 205 insertions(+), 5 deletions(-) create mode 100644 assets/heuristics.toml diff --git a/assets/heuristics.toml b/assets/heuristics.toml new file mode 100644 index 0000000..2fda4ea --- /dev/null +++ b/assets/heuristics.toml @@ -0,0 +1,98 @@ +# Embedded detection-rule metadata. Milestone 3 compiles and executes these +# matchers; Milestone 2 makes their configuration typed, layered, and validated. +schema_version = 1 + +[thresholds] +low = 20 +medium = 50 +high = 75 + +[[rules]] +id = "assistant-self-identification" +category = "prompt-leakage" +matcher = "exact-phrase" +pattern = "As an AI language model" +weight = 30.0 +message = "assistant self-identification appears in the source" +help = "Review whether an assistant response was copied into the document." +occurrence_cap = 1 +enabled = true + +[rules.scope] +content = ["prose"] +extensions = ["md", "txt", "rst", "adoc"] + +[[rules]] +id = "knowledge-cutoff-disclaimer" +category = "prompt-leakage" +matcher = "exact-phrase" +pattern = "knowledge cutoff" +weight = 20.0 +message = "a knowledge-cutoff disclaimer appears in the source" +help = "Verify the statement and remove assistant boilerplate if it is not relevant." +occurrence_cap = 1 +enabled = true + +[rules.scope] +content = ["prose"] +extensions = ["md", "txt", "rst", "adoc"] + +[[rules]] +id = "prompt-response-scaffolding" +category = "prompt-leakage" +matcher = "regex" +pattern = "(?m)^(User|Assistant):[ \\t]" +weight = 25.0 +message = "prompt/response scaffolding appears in the source" +help = "Confirm that chat transcript markers are intentional." +occurrence_cap = 2 +enabled = true + +[rules.scope] +content = ["prose", "source-code"] +extensions = [] + +[[rules]] +id = "templated-conclusion" +category = "style" +matcher = "regex" +pattern = "(?i)\\bin conclusion,? (it is|we can)" +weight = 5.0 +message = "a templated conclusion phrase appears in the source" +help = "Review whether the conclusion adds specific information." +occurrence_cap = 2 +enabled = true + +[rules.scope] +content = ["prose"] +extensions = ["md", "txt", "rst", "adoc"] + +[[rules]] +id = "source-placeholder-todo" +category = "source-code" +matcher = "regex" +pattern = "(?i)\\bTODO:[ \\t]+(implement|add implementation)\\b" +weight = 10.0 +message = "an implementation placeholder remains in source code" +help = "Implement the missing behavior or link the placeholder to tracked work." +occurrence_cap = 3 +enabled = true + +[rules.scope] +content = ["source-code"] +extensions = ["c", "cpp", "go", "java", "js", "py", "rs", "ts"] + +[[rules]] +id = "typography-non-ascii-hyphen" +category = "typography" +matcher = "replacement" +pattern = "configured-replacements" +weight = 10.0 +message = "a configured non-ASCII character has an ASCII replacement" +help = "Review the punctuation or apply the configured safe replacement." +occurrence_cap = 5 +enabled = true + +[rules.scope] +content = ["prose", "source-code"] +extensions = [] diff --git a/src/config.rs b/src/config.rs index 81543c4..5ac1dd3 100644 --- a/src/config.rs +++ b/src/config.rs @@ -6,7 +6,10 @@ use figment::{ }; use serde::{Deserialize, Serialize}; +use crate::Category; + const EMBEDDED_CONFIG: &str = include_str!("../assets/config.toml"); +const EMBEDDED_HEURISTICS: &str = include_str!("../assets/heuristics.toml"); /// One configured Unicode-to-ASCII replacement. #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] @@ -25,17 +28,91 @@ pub struct ReplacementRule { } /// Resolved John Slop configuration. -#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] #[serde(deny_unknown_fields)] pub struct Config { /// Configuration schema understood by this build. pub schema_version: u32, /// Enabled replacement rules in deterministic matching order. pub replacements: Vec, + /// Configured detection rules in deterministic declaration order. + pub rules: Vec, + /// Named confidence-band boundaries. + pub thresholds: ConfidenceThresholds, /// Resource and traversal limits applied while reading inputs. pub input: InputLimits, } +/// One configured data-driven detection rule. +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct HeuristicRule { + /// Stable lowercase kebab-case identifier. + pub id: String, + /// Broad evidence family. + pub category: Category, + /// Matching implementation selected for this rule. + pub matcher: MatcherType, + /// Exact phrase, regular expression, or named replacement source. + pub pattern: String, + /// Evidence contribution before aggregation and damping. + pub weight: f64, + /// Concise explanation shown with a finding. + pub message: String, + /// Remediation or review guidance. + pub help: String, + /// Maximum contributing occurrences per document. + pub occurrence_cap: usize, + /// Whether this rule participates in detection. + pub enabled: bool, + /// Content and extension filters for this rule. + pub scope: RuleScope, +} + +/// Matcher implementation named by a heuristic rule. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "kebab-case")] +pub enum MatcherType { + /// Literal phrase matching. + ExactPhrase, + /// Rust regular-expression matching. + Regex, + /// Findings produced by the configured replacement catalog. + Replacement, +} + +/// Applicability filters attached to a heuristic rule. +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct RuleScope { + /// Broad kinds of content this rule accepts. + pub content: Vec, + /// Lowercase extensions without a leading dot; empty means unrestricted. + pub extensions: Vec, +} + +/// Broad input kind used for heuristic applicability. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "kebab-case")] +pub enum ContentKind { + /// Articles, documentation, and other prose. + Prose, + /// Programming-language source text. + SourceCode, +} + +/// Confidence boundaries used to name aggregate score bands. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] +pub struct ConfidenceThresholds { + /// First score considered low confidence. + pub low: u8, + /// First score considered medium confidence. + pub medium: u8, + /// First score considered high confidence. + pub high: u8, +} + /// Bounded resource policy for filesystem and archive inputs. #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] #[serde(deny_unknown_fields)] @@ -71,8 +148,9 @@ impl Config { /// Load the replacement defaults embedded in this build. pub fn embedded() -> Self { Figment::from(Toml::string(EMBEDDED_CONFIG)) + .merge(Toml::string(EMBEDDED_HEURISTICS)) .extract() - .expect("embedded replacement configuration must be valid") + .expect("embedded configuration must be valid") } } @@ -123,4 +201,22 @@ mod tests { assert_eq!(limits.max_compression_ratio, 100); assert_eq!(limits.max_walk_depth, 64); } + + #[test] + fn embedded_heuristics_have_complete_metadata() { + let config = Config::embedded(); + + assert_eq!(config.rules.len(), 6); + assert_eq!(config.thresholds.low, 20); + assert_eq!(config.thresholds.medium, 50); + assert_eq!(config.thresholds.high, 75); + assert!(config.rules.iter().all(|rule| { + !rule.id.is_empty() + && !rule.pattern.is_empty() + && !rule.message.is_empty() + && !rule.help.is_empty() + && rule.occurrence_cap > 0 + && !rule.scope.content.is_empty() + })); + } } diff --git a/src/lib.rs b/src/lib.rs index 7d62d92..17e3c29 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -12,7 +12,10 @@ mod input; mod model; mod replacement; -pub use config::{Config, InputLimits, ReplacementRule}; +pub use config::{ + ConfidenceThresholds, Config, ContentKind, HeuristicRule, InputLimits, MatcherType, + ReplacementRule, RuleScope, +}; pub use error::{InputError, InputResult}; pub use input::{Document, Documents}; pub use model::{Analysis, Category, Confidence, Finding, RuleId, SourceId, TextEdit}; diff --git a/src/model.rs b/src/model.rs index 3d38a60..b785c63 100644 --- a/src/model.rs +++ b/src/model.rs @@ -2,6 +2,8 @@ use std::{fmt, ops::Range, path::PathBuf}; +use serde::{Deserialize, Serialize}; + /// Stable identifier for a detection rule. #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] pub struct RuleId(String); @@ -25,7 +27,8 @@ impl fmt::Display for RuleId { } /// Broad family of evidence reported by a rule. -#[derive(Debug, Clone, Copy, PartialEq, Eq)] +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "kebab-case")] pub enum Category { /// Suspicious typography or character usage. Typography, diff --git a/tasks.md b/tasks.md index cdabff5..08779f1 100644 --- a/tasks.md +++ b/tasks.md @@ -83,7 +83,7 @@ entry do not discard successful documents. directory crate such as `directories`. - [x] Create `assets/config.toml` as the embedded replacement catalog with `schema_version` and documented examples. -- [ ] Create `assets/heuristics.toml` as a separate embedded rule catalog with +- [x] Create `assets/heuristics.toml` as a separate embedded rule catalog with stable IDs, categories, matcher types, weights, messages, help, occurrence caps, and applicability scopes. - [ ] Implement exact precedence: embedded defaults < user `config.toml` < named