Add diagnostic explanation registry

Author: olwang

README.md

@@ -9,6 +9,7 @@ It currently implements:
 
 - `rss check <file.rss>` with human diagnostics
 - `rss check --json <file.rss>` with serde-backed machine-readable diagnostics
+- `rss check --explain <code>` for diagnostic code explanations
 - `rss fmt <file.rss>` as a parse/check gate that prints the source unchanged when valid
 - `rss review <old.rss> <new.rss>` for a first-pass API/type/effect/freshness diff
 - Lexer, lightweight parser, syntax AST, HIR signature table, and semantic checks for the review-critical v0.4.1 rules
@@ -61,5 +62,6 @@ cargo clippy -- -D warnings
 cargo test
 cargo run --bin rss -- check path/to/file.rss
 cargo run --bin rss -- check --json path/to/file.rss
+cargo run --bin rss -- check --explain RS0401
 cargo run --bin rss -- review old.rss new.rss
 ```

src/diagnostic.rs

@@ -45,6 +45,13 @@ pub struct Diagnostic {
     pub fixes: Vec<Fix>,
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct DiagnosticExplanation {
+    pub code: &'static str,
+    pub title: &'static str,
+    pub explanation: &'static str,
+}
+
 impl Diagnostic {
     pub fn error(
         code: &str,
@@ -100,6 +107,19 @@ impl Diagnostic {
     }
 }
 
+pub fn explain_diagnostic_code(code: &str) -> Option<&'static DiagnosticExplanation> {
+    DIAGNOSTIC_EXPLANATIONS
+        .iter()
+        .find(|explanation| explanation.code == code)
+}
+
+pub fn format_diagnostic_explanation(explanation: &DiagnosticExplanation) -> String {
+    format!(
+        "{}: {}\n\n{}\n",
+        explanation.code, explanation.title, explanation.explanation
+    )
+}
+
 pub fn format_diagnostics_human(diagnostics: &[Diagnostic]) -> String {
     let mut output = String::new();
     for diagnostic in diagnostics {
@@ -131,6 +151,94 @@ pub fn format_diagnostics_human(diagnostics: &[Diagnostic]) -> String {
     output
 }
 
+static DIAGNOSTIC_EXPLANATIONS: &[DiagnosticExplanation] = &[
+    DiagnosticExplanation {
+        code: "RS0001",
+        title: "missing file mode",
+        explanation: "Every RSScript source file must declare `mode: managed` or `mode: uses-local` so reviewers can see whether local ownership features are allowed.",
+    },
+    DiagnosticExplanation {
+        code: "RS0002",
+        title: "missing return type",
+        explanation: "Function signatures must spell out their return type. The checker applies this review rule broadly so API contracts do not rely on inference.",
+    },
+    DiagnosticExplanation {
+        code: "RS0003",
+        title: "missing parameter type",
+        explanation: "Parameters must have explicit types so call effects, freshness, and resource rules can be checked against a stable signature.",
+    },
+    DiagnosticExplanation {
+        code: "RS0004",
+        title: "unknown effect",
+        explanation: "The effect list contains an effect name outside the currently recognized MVP surface.",
+    },
+    DiagnosticExplanation {
+        code: "RS0101",
+        title: "file mode violation",
+        explanation: "`mode: managed` files cannot use local-only features such as `local`, `manage`, `take`, or `ResourcePool<T>`.",
+    },
+    DiagnosticExplanation {
+        code: "RS0201",
+        title: "unnamed argument",
+        explanation: "RSScript requires named call arguments so signature and review diffs remain readable.",
+    },
+    DiagnosticExplanation {
+        code: "RS0202",
+        title: "missing call-site data effect",
+        explanation: "Arguments for non-Copy parameters must use an explicit `read`, `mut`, or `take` effect matching the callee signature.",
+    },
+    DiagnosticExplanation {
+        code: "RS0301",
+        title: "managed-to-local conversion",
+        explanation: "Managed values cannot be rebound as local values. Create the value locally at its origin if local ownership is required.",
+    },
+    DiagnosticExplanation {
+        code: "RS0401",
+        title: "use after manage",
+        explanation: "`manage value` moves a local value into the managed runtime. The original local binding cannot be used afterwards on any reachable path.",
+    },
+    DiagnosticExplanation {
+        code: "RS0501",
+        title: "local value retained",
+        explanation: "APIs marked `effects(retains(param))` may store the argument beyond the call. Passing a clean local value directly would let local ownership escape.",
+    },
+    DiagnosticExplanation {
+        code: "RS0601",
+        title: "fresh return is not clean",
+        explanation: "A `fresh` function may only return a newly created value, a known fresh call, or a clean local value that has not escaped through manage, take, retain, or capture.",
+    },
+    DiagnosticExplanation {
+        code: "RS0602",
+        title: "freshness unknown",
+        explanation: "The MVP checker could not prove the returned value is fresh. Current proof support trusts clean locals, struct constructors, and known fresh calls.",
+    },
+    DiagnosticExplanation {
+        code: "RS0701",
+        title: "resource field",
+        explanation: "Resource values cannot be stored directly in ordinary class or struct fields. Use `with` or an approved resource container such as `ResourcePool<T>`.",
+    },
+    DiagnosticExplanation {
+        code: "RS0702",
+        title: "resource escape",
+        explanation: "A resource introduced by `with` must not escape the block through return, manage, retention, or managed closure capture.",
+    },
+    DiagnosticExplanation {
+        code: "RS0801",
+        title: "local captured by managed closure",
+        explanation: "A closure bound with `let` is managed and may outlive clean local values. Use a local/noescape callback shape instead.",
+    },
+    DiagnosticExplanation {
+        code: "RS0901",
+        title: "take of handle field",
+        explanation: "Handle fields are managed references. They cannot be consumed with `take` as if they were inline local fields.",
+    },
+    DiagnosticExplanation {
+        code: "RS1001",
+        title: "operator overload attempt",
+        explanation: "The MVP language surface rejects likely user-defined operator overloads to keep review semantics explicit.",
+    },
+];
+
 pub fn format_diagnostics_json(diagnostics: &[Diagnostic]) -> String {
     let diagnostics: Vec<JsonDiagnostic<'_>> =
         diagnostics.iter().map(JsonDiagnostic::from).collect();

src/lib.rs

@@ -8,5 +8,8 @@ mod review;
 pub mod syntax;
 
 pub use analyzer::analyze_source;
-pub use diagnostic::{Diagnostic, Severity, format_diagnostics_human, format_diagnostics_json};
+pub use diagnostic::{
+    Diagnostic, DiagnosticExplanation, Severity, explain_diagnostic_code,
+    format_diagnostic_explanation, format_diagnostics_human, format_diagnostics_json,
+};
 pub use review::{ReviewFinding, format_review_human, review_sources};

src/main.rs

@@ -3,8 +3,8 @@ use std::fs;
 use std::process::ExitCode;
 
 use rsscript::{
-    analyze_source, format_diagnostics_human, format_diagnostics_json, format_review_human,
-    review_sources,
+    analyze_source, explain_diagnostic_code, format_diagnostic_explanation,
+    format_diagnostics_human, format_diagnostics_json, format_review_human, review_sources,
 };
 
 fn main() -> ExitCode {
@@ -26,6 +26,15 @@ fn main() -> ExitCode {
 }
 
 fn run_check(args: &[String]) -> ExitCode {
+    if let Some(code) = parse_explain_args(args) {
+        let Some(explanation) = explain_diagnostic_code(code) else {
+            eprintln!("unknown diagnostic code: {code}");
+            return ExitCode::from(2);
+        };
+        print!("{}", format_diagnostic_explanation(explanation));
+        return ExitCode::SUCCESS;
+    }
+
     let (json, path) = parse_path_args(args);
     let Some(path) = path else {
         print_usage();
@@ -125,6 +134,13 @@ fn run_review(args: &[String]) -> ExitCode {
     ExitCode::SUCCESS
 }
 
+fn parse_explain_args(args: &[String]) -> Option<&str> {
+    let [flag, code] = args else {
+        return None;
+    };
+    (flag == "--explain").then_some(code.as_str())
+}
+
 fn parse_path_args(args: &[String]) -> (bool, Option<&str>) {
     let mut json = false;
     let mut path = None;
@@ -143,6 +159,7 @@ fn parse_path_args(args: &[String]) -> (bool, Option<&str>) {
 fn print_usage() {
     eprintln!("usage:");
     eprintln!("  rsscript check [--json] <file.rss>");
+    eprintln!("  rsscript check --explain <code>");
     eprintln!("  rsscript fmt <file.rss>");
     eprintln!("  rsscript review <old.rss> <new.rss>");
 }

tests/checker.rs

@@ -3,7 +3,10 @@ use std::path::{Path, PathBuf};
 
 use rsscript::syntax::ast::Item;
 use rsscript::syntax::parse_source;
-use rsscript::{analyze_source, format_diagnostics_json, review_sources};
+use rsscript::{
+    analyze_source, explain_diagnostic_code, format_diagnostic_explanation,
+    format_diagnostics_json, review_sources,
+};
 use serde_json::Value;
 
 #[test]
@@ -63,6 +66,17 @@ fn diagnostics_json_uses_protocol_shape() {
     assert!(first["fixes"].is_array());
 }
 
+#[test]
+fn diagnostic_explanations_are_available_by_code() {
+    let explanation = explain_diagnostic_code("RS0401").expect("RS0401 should be registered");
+    let formatted = format_diagnostic_explanation(explanation);
+
+    assert_eq!(explanation.title, "use after manage");
+    assert!(formatted.contains("RS0401"));
+    assert!(formatted.contains("manage"));
+    assert!(explain_diagnostic_code("RS9999").is_none());
+}
+
 #[test]
 fn syntax_parser_accepts_all_fixtures() {
     let mut paths = fixture_paths("tests/fixtures/pass");