Add remediation hints to review JSON

Author: olwang

README.md

@@ -2,6 +2,8 @@
 
 This is a Rust implementation of an RSScript v0.4.1 review-first front-end MVP.
 
+## Goal
+
 RSScript is designed for AI-generated code that humans still need to review. It
 makes mutation, retention, resource lifetime, and local-performance boundaries
 visible in source code and machine-readable diagnostics.
@@ -15,7 +17,7 @@ It currently implements:
 - `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>` and `rss review --json <old.rss> <new.rss>` for first-pass API/type/effect/freshness diffs with structured risk categories, spans, before/after values, and path-aware local/manage boundary summaries
+- `rss review <old.rss> <new.rss>` and `rss review --json <old.rss> <new.rss>` for first-pass API/type/effect/freshness diffs with structured risk categories, spans, before/after values, remediation hints, and path-aware local/manage boundary summaries
 - Lexer, lightweight parser, syntax AST, HIR signature table, and semantic checks for the review-critical v0.4.1 rules
 - Builtin signatures for the current fixture stdlib surface, including `Image`, `File`, `Map`, `ResourcePool`, `Json`, `Csv`, database/resource helpers, and cache/config helpers
 - HIR type and field tables for class/struct/resource declarations and handle fields
@@ -61,7 +63,7 @@ Implemented diagnostic classes include:
 - local capture by managed closures
 - local capture by closures passed to retaining APIs
 - `take` of handle fields
-- API, type layout, path-aware local/manage boundary, effect, mode, and freshness changes in `rss review`, tagged with structured risk categories, spans, and before/after values in JSON output
+- API, type layout, path-aware local/manage boundary, effect, mode, and freshness changes in `rss review`, tagged with structured risk categories, spans, before/after values, and remediation hints in JSON output
 - likely operator overload attempts
 
 Non-goals for this stage:
@@ -79,7 +81,7 @@ Non-goals for this stage:
 Near-term roadmap:
 
 1. Expand local/resource dataflow precision around typed `ResourcePool<T>` lease propagation and expression-order coverage for short-circuiting/control expressions.
-2. Expand `rss review` JSON with richer machine-applicable remediation hints.
+2. Expand `rss review` JSON remediation hints into machine-applicable edits where possible.
 
 Run:
 

src/lib.rs

@@ -12,5 +12,5 @@ pub use diagnostic::{
     format_diagnostic_explanation, format_diagnostics_human, format_diagnostics_json,
 };
 pub use review::{
-    ReviewFinding, ReviewRisk, format_review_human, format_review_json, review_sources,
+    ReviewFinding, ReviewFix, ReviewRisk, format_review_human, format_review_json, review_sources,
 };

src/review.rs

@@ -19,6 +19,7 @@ pub struct ReviewFinding {
     pub before: Option<String>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub after: Option<String>,
+    pub fixes: Vec<ReviewFix>,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize)]
@@ -30,6 +31,13 @@ pub struct ReviewSpan {
     pub label: String,
 }
 
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+pub struct ReviewFix {
+    pub kind: String,
+    pub title: String,
+    pub applicability: String,
+}
+
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
 #[serde(rename_all = "kebab-case")]
 pub enum ReviewRisk {
@@ -174,7 +182,63 @@ fn review_finding(
         spans,
         before,
         after,
-    }
+        fixes: review_fixes(code),
+    }
+}
+
+fn review_fixes(code: &str) -> Vec<ReviewFix> {
+    let (kind, title) = match code {
+        code::REVIEW_MODE_CHANGED => (
+            "review_file_mode",
+            "Review whether this file should allow local ownership features.",
+        ),
+        code::REVIEW_FUNCTION_REMOVED => (
+            "restore_or_migrate_function",
+            "Restore the function or migrate all call sites.",
+        ),
+        code::REVIEW_FUNCTION_ADDED => (
+            "review_new_api",
+            "Review the new API surface and ownership contract.",
+        ),
+        code::REVIEW_PARAMS_CHANGED => (
+            "update_call_sites",
+            "Update call sites for the changed parameter contract.",
+        ),
+        code::REVIEW_RETURN_CHANGED => (
+            "review_return_contract",
+            "Review callers that depend on the old return and freshness contract.",
+        ),
+        code::REVIEW_EFFECTS_CHANGED => (
+            "review_effect_contract",
+            "Review added or removed effects and update callers.",
+        ),
+        code::REVIEW_TYPE_REMOVED => (
+            "restore_or_migrate_type",
+            "Restore the type or migrate all consumers.",
+        ),
+        code::REVIEW_TYPE_ADDED => (
+            "review_type_exposure",
+            "Review the new type's ownership and resource fields.",
+        ),
+        code::REVIEW_TYPE_KIND_CHANGED => (
+            "review_type_kind",
+            "Review class, struct, or resource lifetime semantics for this type.",
+        ),
+        code::REVIEW_TYPE_FIELDS_CHANGED => (
+            "review_type_layout",
+            "Review field ownership, handle markers, and resource containment.",
+        ),
+        code::REVIEW_BOUNDARY_CHANGED => (
+            "review_local_manage_boundary",
+            "Review the changed local ownership and manage boundary.",
+        ),
+        _ => ("review_change", "Review this source-level contract change."),
+    };
+    vec![ReviewFix {
+        kind: kind.to_string(),
+        title: title.to_string(),
+        applicability: "manual".to_string(),
+    }]
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]

tests/checker.rs

@@ -123,6 +123,17 @@ fn render(path: take Path) -> fresh Image
             .as_array()
             .is_some_and(|spans| spans.len() == 2)
     );
+    let effect_fixes = effect["fixes"]
+        .as_array()
+        .expect("review finding should include fixes");
+    assert!(effect_fixes.iter().any(|fix| {
+        fix["kind"] == "review_effect_contract" && fix["applicability"] == "manual"
+    }));
+    assert!(items.iter().all(|item| {
+        item["fixes"]
+            .as_array()
+            .is_some_and(|fixes| !fixes.is_empty())
+    }));
     assert!(items.iter().all(|item| {
         item["summary"]
             .as_str()
@@ -307,6 +318,12 @@ fn publish(path: read Path) -> Unit {
     assert!(boundary.summary.contains("body[1]"));
     assert!(boundary.summary.contains("body[2].value"));
     assert_eq!(boundary.risk, ReviewRisk::Boundary);
+    assert!(
+        boundary
+            .fixes
+            .iter()
+            .any(|fix| fix.kind == "review_local_manage_boundary")
+    );
 }
 
 fn fixture_paths(directory: &str) -> Vec<PathBuf> {