Add rss lint signature complexity warnings

Author: olwang

README.md

@@ -400,6 +400,7 @@ Current CLI surface:
 ```sh
 rss check [--json] [--core|--no-core] [--interface <file.rssi> ...] <file.rss>
 rss check --explain <code>
+rss lint [--json] [--core|--no-core] [--interface <file.rssi> ...] <file.rss>
 rss fmt <file.rss>
 rss review [--json] --diff <old.rss> <new.rss>
 rss review [--json] --map <file-or-directory>
@@ -414,6 +415,8 @@ rss verify-rust [--json] <file.rss> --out-dir <directory>
 
 `rss check` loads bundled core `.rssi` signatures by default. Use `--no-core` only when testing a file against user-supplied interfaces in isolation. Bundled signatures are ordinary `.rssi` files under `core/`, not a second Rust-side builtin table.
 
+`rss lint` runs the same frontend checks and emits warning diagnostics for reviewability issues. The first lint is `RSL001`, which flags public signatures that exceed the current review budget for parameter count, generic parameter count, effect count, or nested type depth.
+
 If a lowered package contains `fn main() -> Unit` or `fn main() -> Result<Unit, E>`, `rss lower --rust --out-dir` also emits a Rust `src/main.rs` harness. `rss run <file.rss>` uses the same lowering path, writes a temporary Rust package, and delegates execution to `cargo run`. Use `rss run <file.rss> --out-dir <directory>` to keep the generated Rust package for inspection.
 
 `rss verify-rust <file.rss> --out-dir <directory>` keeps the generated package used for backend checking, including `rsscript-source-map.json`, so unmappable rustc diagnostics can be inspected against the generated Rust.

src/diagnostic.rs

@@ -48,6 +48,7 @@ pub mod code {
     pub const SURFACE_REFERENCE_ATTEMPT: &str = "RS1004";
     pub const RUSTC_DIAGNOSTIC_MAPPED: &str = "RS1101";
     pub const RUSTC_DIAGNOSTIC_UNMAPPABLE: &str = "RS1102";
+    pub const LINT_SIGNATURE_COMPLEXITY: &str = "RSL001";
 
     pub const REVIEW_FEATURES_CHANGED: &str = "RSR001";
     pub const REVIEW_FUNCTION_REMOVED: &str = "RSR002";
@@ -452,6 +453,11 @@ static DIAGNOSTIC_EXPLANATIONS: &[DiagnosticExplanation] = &[
         title: "unmappable rustc diagnostic",
         explanation: "rustc reported a backend diagnostic whose generated Rust location could not be mapped back to RSScript source. The compiler should surface the generated Rust reference as secondary internal detail instead of exposing raw rustc output as the primary diagnostic.",
     },
+    DiagnosticExplanation {
+        code: code::LINT_SIGNATURE_COMPLEXITY,
+        title: "signature complexity lint",
+        explanation: "Public signatures should remain reviewable in one screen. The linter warns when public parameters, generic parameters, effect clauses, or nested type shapes exceed the current review budget.",
+    },
 ];
 
 pub fn format_diagnostics_json(diagnostics: &[Diagnostic]) -> String {

src/lib.rs

@@ -4,6 +4,7 @@ mod diagnostic;
 mod hir;
 mod interfaces;
 mod lexer;
+mod lint;
 mod review;
 mod rust_lower;
 pub mod syntax;
@@ -15,6 +16,7 @@ pub use diagnostic::{
     Diagnostic, DiagnosticExplanation, Severity, explain_diagnostic_code,
     format_diagnostic_explanation, format_diagnostics_human, format_diagnostics_json,
 };
+pub use lint::lint_source;
 pub use review::{
     ReviewFinding, ReviewFix, ReviewMap, ReviewMapCategorySummary, ReviewMapClassification,
     ReviewMapFile, ReviewMapFileRisk, ReviewMapRegion, ReviewMapSummary, ReviewRisk,

src/lint.rs

@@ -0,0 +1,125 @@
+use crate::diagnostic::{Diagnostic, Span, code};
+use crate::syntax::ast::{Item, TypeRef};
+use crate::syntax::parse_source;
+
+const MAX_PUBLIC_PARAMS: usize = 6;
+const MAX_PUBLIC_GENERICS: usize = 3;
+const MAX_PUBLIC_EFFECTS: usize = 4;
+const MAX_TYPE_DEPTH: usize = 4;
+
+pub fn lint_source(file: &str, source: &str) -> Vec<Diagnostic> {
+    let program = parse_source(file, source);
+    let mut diagnostics = Vec::new();
+
+    for item in program.items {
+        let Item::Function(function) = item else {
+            continue;
+        };
+        if !function.is_public {
+            continue;
+        }
+
+        if function.params.len() > MAX_PUBLIC_PARAMS {
+            signature_complexity_warning(
+                &mut diagnostics,
+                function.span.clone(),
+                format!(
+                    "Public function `{}` has {} parameters.",
+                    function.name,
+                    function.params.len()
+                ),
+                format!(
+                    "Keep public signatures at or below {MAX_PUBLIC_PARAMS} parameters, or group related values into a reviewable struct."
+                ),
+            );
+        }
+
+        if function.type_params.len() > MAX_PUBLIC_GENERICS {
+            signature_complexity_warning(
+                &mut diagnostics,
+                function.span.clone(),
+                format!(
+                    "Public function `{}` has {} generic parameters.",
+                    function.name,
+                    function.type_params.len()
+                ),
+                format!(
+                    "Keep public signatures at or below {MAX_PUBLIC_GENERICS} generic parameters."
+                ),
+            );
+        }
+
+        if function.effects.len() > MAX_PUBLIC_EFFECTS {
+            signature_complexity_warning(
+                &mut diagnostics,
+                function.span.clone(),
+                format!(
+                    "Public function `{}` declares {} effects.",
+                    function.name,
+                    function.effects.len()
+                ),
+                format!("Keep public effect clauses at or below {MAX_PUBLIC_EFFECTS} entries."),
+            );
+        }
+
+        for param in &function.params {
+            let depth = type_depth(&param.ty);
+            if depth > MAX_TYPE_DEPTH {
+                signature_complexity_warning(
+                    &mut diagnostics,
+                    param.span.clone(),
+                    format!(
+                        "Parameter `{}` in public function `{}` has nested type depth {}.",
+                        param.name, function.name, depth
+                    ),
+                    format!(
+                        "Keep public parameter types at or below nesting depth {MAX_TYPE_DEPTH}."
+                    ),
+                );
+            }
+        }
+
+        if let Some(return_ty) = &function.return_ty {
+            let depth = type_depth(return_ty);
+            if depth > MAX_TYPE_DEPTH {
+                signature_complexity_warning(
+                    &mut diagnostics,
+                    return_ty.span.clone(),
+                    format!(
+                        "Return type of public function `{}` has nested type depth {}.",
+                        function.name, depth
+                    ),
+                    format!("Keep public return types at or below nesting depth {MAX_TYPE_DEPTH}."),
+                );
+            }
+        }
+    }
+
+    diagnostics
+}
+
+fn signature_complexity_warning(
+    diagnostics: &mut Vec<Diagnostic>,
+    span: Span,
+    summary: impl Into<String>,
+    cause: impl Into<String>,
+) {
+    diagnostics.push(
+        Diagnostic::warning(
+            code::LINT_SIGNATURE_COMPLEXITY,
+            summary,
+            span,
+            "signature complexity",
+        )
+        .with_cause(cause)
+        .with_fix(
+            "simplify_public_signature",
+            "Simplify this public signature so it remains reviewable in one screen.",
+            "manual",
+        ),
+    );
+}
+
+fn type_depth(ty: &TypeRef) -> usize {
+    1 + ty.args.iter().map(type_depth).max().unwrap_or(0)
+}

src/main.rs

@@ -8,7 +8,7 @@ use rsscript::{
     Diagnostic, analyze_source, analyze_source_with_interfaces, check_generated_rust_package,
     core_interfaces, explain_diagnostic_code, format_diagnostic_explanation,
     format_diagnostics_human, format_diagnostics_json, format_review_human, format_review_json,
-    format_review_map_human, format_review_map_json, lower_source_to_rust,
+    format_review_map_human, format_review_map_json, lint_source, lower_source_to_rust,
     lower_source_to_rust_package, parse_source_map_json, remap_rustc_diagnostic_json_lines,
     review_map_sources, review_sources, write_generated_rust_package,
 };
@@ -22,6 +22,7 @@ fn main() -> ExitCode {
 
     match command {
         "check" => run_check(&args[2..]),
+        "lint" => run_lint(&args[2..]),
         "fmt" => run_fmt(&args[2..]),
         "review" => run_review(&args[2..]),
         "lower" => run_lower(&args[2..]),
@@ -35,6 +36,61 @@ fn main() -> ExitCode {
     }
 }
 
+fn run_lint(args: &[String]) -> ExitCode {
+    let options = parse_check_args(args);
+    let Some(path) = options.path else {
+        print_usage();
+        return ExitCode::from(2);
+    };
+
+    let source = match fs::read_to_string(path) {
+        Ok(source) => source,
+        Err(error) => {
+            eprintln!("failed to read {path}: {error}");
+            return ExitCode::from(2);
+        }
+    };
+
+    let interfaces = match read_interface_sources(&options.interfaces) {
+        Ok(interfaces) => interfaces,
+        Err(error) => {
+            eprintln!("{error}");
+            return ExitCode::from(2);
+        }
+    };
+    let interface_refs = interfaces
+        .iter()
+        .map(|interface| (interface.path.as_str(), interface.contents.as_str()))
+        .collect::<Vec<_>>();
+    let mut diagnostics = if options.use_core {
+        let mut combined = core_interfaces().to_vec();
+        combined.extend(interface_refs);
+        analyze_source_with_interfaces(path, &source, &combined)
+    } else if interface_refs.is_empty() {
+        analyze_source(path, &source)
+    } else {
+        analyze_source_with_interfaces(path, &source, &interface_refs)
+    };
+    diagnostics.extend(lint_source(path, &source));
+
+    if options.json {
+        println!("{}", format_diagnostics_json(&diagnostics));
+    } else if diagnostics.is_empty() {
+        println!("{path}: lint ok");
+    } else {
+        print!("{}", format_diagnostics_human(&diagnostics));
+    }
+
+    if diagnostics
+        .iter()
+        .any(|diagnostic| diagnostic.severity.is_error())
+    {
+        ExitCode::from(1)
+    } else {
+        ExitCode::SUCCESS
+    }
+}
+
 fn run_check(args: &[String]) -> ExitCode {
     if let Some(code) = parse_explain_args(args) {
         let Some(explanation) = explain_diagnostic_code(code) else {
@@ -835,6 +891,9 @@ fn print_usage() {
     eprintln!(
         "  rsscript check [--json] [--core|--no-core] [--interface <file.rssi> ...] <file.rss>"
     );
+    eprintln!(
+        "  rsscript lint [--json] [--core|--no-core] [--interface <file.rssi> ...] <file.rss>"
+    );
     eprintln!("  rsscript check --explain <code>");
     eprintln!("  rsscript fmt <file.rss>");
     eprintln!("  rsscript lower --rust <file.rss>");

tests/checker.rs

@@ -8,7 +8,7 @@ use rsscript::{
     analyze_source_with_core, analyze_source_with_interfaces, core_interfaces,
     explain_diagnostic_code, format_diagnostic_explanation, format_diagnostics_json,
     format_review_human, format_review_json, format_review_map_human, format_review_map_json,
-    lower_source_to_rust, lower_source_to_rust_package, lower_source_to_rust_with_map,
+    lint_source, lower_source_to_rust, lower_source_to_rust_package, lower_source_to_rust_with_map,
     remap_rustc_diagnostic_json, remap_rustc_diagnostic_json_lines, review_map_sources,
     review_sources,
 };
@@ -196,6 +196,52 @@ fn diagnostic_explanations_are_available_by_code() {
     assert!(explain_diagnostic_code("RS9999").is_none());
 }
 
+#[test]
+fn lint_warns_on_public_signature_complexity() {
+    let source = r#"
+pub fn overloaded<A, B, C, D>(
+    first: read Result<Option<List<Map<String, Image>>>, Error>,
+    second: read String,
+    third: read String,
+    fourth: read String,
+    fifth: read String,
+    sixth: read String,
+    seventh: read String,
+) -> Result<Option<List<Map<String, Image>>>, Error>
+    effects(no_panic, noalloc, no_block, pure, native)
+{
+    return Ok(None)
+}
+"#;
+    let diagnostics = lint_source("lint.rss", source);
+    let codes = diagnostics
+        .iter()
+        .map(|diagnostic| diagnostic.code.as_str())
+        .collect::<Vec<_>>();
+
+    assert!(codes.contains(&"RSL001"));
+    assert!(
+        diagnostics
+            .iter()
+            .all(|diagnostic| !diagnostic.severity.is_error())
+    );
+    assert!(
+        diagnostics
+            .iter()
+            .any(|diagnostic| diagnostic.summary.contains("7 parameters"))
+    );
+    assert!(
+        diagnostics
+            .iter()
+            .any(|diagnostic| diagnostic.summary.contains("4 generic parameters"))
+    );
+    assert!(
+        diagnostics
+            .iter()
+            .any(|diagnostic| diagnostic.summary.contains("5 effects"))
+    );
+}
+
 #[test]
 fn parser_accepts_qualified_interface_function_signatures() {
     let source = r#"