feat: embed typed heuristic catalog

This commit is contained in:
Dandaedre 2026-09-29 13:17:48 +02:00
parent 845fb891f2
commit 177337c0ae
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
5 changed files with 205 additions and 5 deletions

98
assets/heuristics.toml Normal file
View File

@ -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 = []

View File

@ -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<ReplacementRule>,
/// Configured detection rules in deterministic declaration order.
pub rules: Vec<HeuristicRule>,
/// 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<ContentKind>,
/// Lowercase extensions without a leading dot; empty means unrestricted.
pub extensions: Vec<String>,
}
/// 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()
}));
}
}

View File

@ -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};

View File

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

View File

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