feat(mling): add linter framework with async support and registry

generation

15 files changed, 1003 insertions, 22 deletions

diff --git a/mingling_cli/src/diagnostic.rs b/mingling_cli/src/diagnostic.rs
new file mode 100644
index 0000000..527e879
--- /dev/null
+++ b/mingling_cli/src/diagnostic.rs
@@ -0,0 +1,99 @@
+use annotate_snippets::level::{ERROR, HELP, NOTE, WARNING};
+use annotate_snippets::{AnnotationKind, Group, Renderer, Snippet};
+use cargo_metadata::diagnostic::Diagnostic;
+use mingling::macros::{buffer, group, r_println, renderer};
+
+group!(Diagnostic);
+
+#[renderer(buffer)]
+pub fn render_diagnostic(diagnostic: Diagnostic) {
+    let report = diagnostic_to_report(&diagnostic);
+    let renderer = Renderer::styled();
+    let rendered = renderer.render(&report);
+    r_println!("{rendered}");
+}
+
+fn cargo_level_to_annotate(
+    level: cargo_metadata::diagnostic::DiagnosticLevel,
+) -> &'static annotate_snippets::Level<'static> {
+    use cargo_metadata::diagnostic::DiagnosticLevel;
+    match level {
+        DiagnosticLevel::Ice | DiagnosticLevel::Error => &ERROR,
+        DiagnosticLevel::Warning => &WARNING,
+        DiagnosticLevel::Note | DiagnosticLevel::FailureNote => &NOTE,
+        DiagnosticLevel::Help => &HELP,
+        _ => &ERROR,
+    }
+}
+
+/// 把 1-based char offset 转成 0-based byte offset
+fn char_offset_to_byte_offset(s: &str, char_offset: usize) -> usize {
+    s.char_indices()
+        .nth(char_offset.saturating_sub(1))
+        .map(|(i, _)| i)
+        .unwrap_or(s.len())
+}
+
+fn diagnostic_to_report<'a>(d: &'a Diagnostic) -> Vec<Group<'a>> {
+    let level = cargo_level_to_annotate(d.level);
+    let mut title = level.clone().primary_title(d.message.as_str());
+    if let Some(ref code) = d.code {
+        title = title.id(code.code.as_str());
+    }
+
+    let mut group = Group::with_title(title);
+
+    for span in &d.spans {
+        if !span.is_primary {
+            continue;
+        }
+
+        let source: String = span
+            .text
+            .iter()
+            .map(|l| l.text.as_str())
+            .collect::<Vec<_>>()
+            .join("\n");
+
+        let byte_range = if span.text.len() == 1 {
+            let line = &span.text[0];
+            let start = char_offset_to_byte_offset(&line.text, line.highlight_start);
+            let end = char_offset_to_byte_offset(&line.text, line.highlight_end);
+            start..end
+        } else {
+            let first = &span.text[0];
+            let last = span.text.last().unwrap();
+            let start = char_offset_to_byte_offset(&first.text, first.highlight_start);
+            let prefix_len: usize = span.text[..span.text.len() - 1]
+                .iter()
+                .map(|l| l.text.len() + 1)
+                .sum();
+            let end = prefix_len + char_offset_to_byte_offset(&last.text, last.highlight_end);
+            start..end
+        };
+
+        let mut snippet = Snippet::source(source)
+            .line_start(span.line_start)
+            .path(span.file_name.as_str());
+
+        if let Some(ref label) = span.label {
+            let annotation = AnnotationKind::Primary
+                .span(byte_range)
+                .label(label.as_str());
+            snippet = snippet.annotation(annotation);
+        } else {
+            let annotation = AnnotationKind::Primary.span(byte_range);
+            snippet = snippet.annotation(annotation);
+        }
+
+        group = group.element(snippet);
+    }
+
+    for child in &d.children {
+        let msg_level = cargo_level_to_annotate(child.level);
+        let msg = msg_level.clone().message(child.message.as_str());
+        group = group.element(msg);
+    }
+
+    vec![group]
+}
diff --git a/mingling_cli/src/errors.rs b/mingling_cli/src/errors.rs
new file mode 100644
index 0000000..cef9616
--- /dev/null
+++ b/mingling_cli/src/errors.rs
@@ -0,0 +1 @@
+pub mod serde_json;
diff --git a/mingling_cli/src/errors/serde_json.rs b/mingling_cli/src/errors/serde_json.rs
new file mode 100644
index 0000000..c73329c
--- /dev/null
+++ b/mingling_cli/src/errors/serde_json.rs
@@ -0,0 +1,8 @@
+use mingling::macros::{buffer, group, r_println, renderer};
+
+group!(ErrorSerdeJson = serde_json::Error);
+
+#[renderer(buffer)]
+pub fn render_error_serde_json(_err: ErrorSerdeJson) {
+    r_println!("serde");
+}
diff --git a/mingling_cli/src/linter.rs b/mingling_cli/src/linter.rs
index 870efeb..b3b2e7b 100644
--- a/mingling_cli/src/linter.rs
+++ b/mingling_cli/src/linter.rs
@@ -3,6 +3,8 @@ use mingling::{Program, macros::program_setup};
 use crate::linter::cmd_mlint::CMDMinglingLinter;
 
 pub mod cmd_mlint;
+pub mod mlint_attr;
+pub mod mlint_report;
 
 #[program_setup]
 pub fn mingling_linter_setup(program: &mut Program<crate::ThisProgram>) {
diff --git a/mingling_cli/src/linter/cmd_mlint.rs b/mingling_cli/src/linter/cmd_mlint.rs
index 1431c43..90871af 100644
--- a/mingling_cli/src/linter/cmd_mlint.rs
+++ b/mingling_cli/src/linter/cmd_mlint.rs
@@ -1,6 +1,119 @@
-use mingling::macros::{chain, dispatcher};
+use crate::linter::mlint_report::{MlintReport, StateLintReports};
+use cargo_metadata::Metadata;
+use mingling::LazyRes;
+use mingling::consts::REMAINS;
+use mingling::macros::{arg, chain, dispatcher, pack};
+use mingling::picker::EntryPicker;
 
-dispatcher!("mlint", CMDMinglingLinter => EntryMinglingLinter);
+dispatcher!("lint", CMDMinglingLinter => EntryMinglingLinter);
+
+/// Main linting function that processes all packages in the metadata.
+///
+/// Iterates through all packages and their targets (e.g., binaries, libraries, tests),
+/// reads Rust source files (`.rs`), parses them into ASTs, runs lint checks,
+/// and enriches each report with metadata information.
+async fn linter_main(metadata: &Metadata) -> Vec<MlintReport> {
+    // Vector to accumulate all lint reports
+    let mut all_reports = Vec::new();
+
+    // Iterate over all packages in the metadata
+    for package in &metadata.packages {
+        // Iterate over all targets within a package (e.g., bin, lib, test, etc.)
+        for target in &package.targets {
+            let path = &target.src_path;
+            // Only process Rust source files (with `.rs` extension)
+            if !path.as_str().ends_with(".rs") {
+                continue;
+            }
+            // Read the source file content
+            let source = match std::fs::read_to_string(path.as_str()) {
+                Ok(s) => s,
+                Err(_) => continue,
+            };
+            // Parse the source file into an AST (Abstract Syntax Tree)
+            let ast = match syn::parse_file(&source) {
+                Ok(f) => f,
+                Err(_) => continue,
+            };
+
+            // Run all lint checks and collect reports
+            let reports = crate::lints::run_all_lints(&ast, &source);
+            //
+            for mut r in reports {
+                // Enrich report with metadata information
+                r.file_name = path.as_str().to_string();
+                r.source_code = source.clone();
+                r.package_id = Some(package.id.to_string());
+                r.target_name = Some(target.name.clone());
+                r.target_kind = target.kind.first().map(|k| k.to_string());
+                r.target_src_path = Some(path.as_str().to_string());
+                all_reports.push(r);
+            }
+        }
+    }
+
+    all_reports
+}
+
+pack!(StateBeginLinter = ());
+
+#[chain]
+pub fn handle_lint(args: EntryMinglingLinter) -> StateBeginLinter {
+    let (with_checker, checker_args) = args
+        .pick_or(&arg![with_checker: Option<String>], || {
+            Some("cargo,check".to_string())
+        })
+        .pick(&REMAINS)
+        .unwrap();
+
+    // If with_checker is not set, proceed directly to the mingling lint phase
+    let Some(with_checker) = with_checker else {
+        return StateBeginLinter::new(());
+    };
+
+    let with_checker: Vec<&str> = with_checker.split(',').collect();
+    let checker_args: Vec<String> = checker_args.into();
+
+    // Run the outer checker (e.g. cargo check) with output passed through directly
+    execute_checker(&with_checker, checker_args.as_slice());
+
+    StateBeginLinter::new(())
+}
+
+/// Run the outer checker (e.g. cargo check) with output passed through directly.
+fn execute_checker(with_checker: &[&str], checker_args: &[String]) {
+    if with_checker.is_empty() {
+        return;
+    }
+
+    let checker_str = with_checker.join(" ");
+    let args_str = checker_args.join(" ");
+    let full_cmd = if args_str.is_empty() {
+        checker_str
+    } else {
+        format!("{} {}", checker_str, args_str)
+    };
+
+    let mut cmd = if cfg!(target_os = "windows") {
+        let mut c = std::process::Command::new("cmd");
+        c.args(["/C", &full_cmd]);
+        c
+    } else {
+        let mut c = std::process::Command::new("sh");
+        c.args(["-c", &full_cmd]);
+        c
+    };
+
+    // Pass through stdin/stdout/stderr so the user sees everything
+    let _ = cmd.status();
+}
 
 #[chain]
-pub fn handle_mlint(_args: EntryMinglingLinter) {}
+pub async fn handle_state_begin_linter(
+    _: StateBeginLinter,
+    metadata: &mut LazyRes<crate::metadata::setup::ResMetadata>,
+) -> StateLintReports {
+    let metadata = metadata.get_ref().data();
+    let reports = linter_main(metadata).await;
+    StateLintReports::new(reports)
+}
diff --git a/mingling_cli/src/linter/mlint_attr.rs b/mingling_cli/src/linter/mlint_attr.rs
new file mode 100644
index 0000000..24528d4
--- /dev/null
+++ b/mingling_cli/src/linter/mlint_attr.rs
@@ -0,0 +1,39 @@
+/// Result of checking `mlint(allow/warn/deny(...))` attributes.
+#[derive(Clone, Copy, PartialEq, Eq)]
+pub enum MlintLevelOverride {
+    Allow,
+    Warn,
+    Deny,
+}
+
+/// Parse `mlint(allow/warn/deny(lint_name))` from attributes.
+/// Returns `None` if the lint is not mentioned in any mlint attribute.
+pub fn get_mlint_override(attrs: &[syn::Attribute], lint_name: &str) -> Option<MlintLevelOverride> {
+    for attr in attrs {
+        if !attr.path().is_ident("mlint") {
+            continue;
+        }
+        let list = match attr.meta.require_list() {
+            Ok(l) => l,
+            Err(_) => continue,
+        };
+        // TokenStream::to_string() adds spaces between tokens,
+        // e.g. `allow(xxx)` → `allow ( xxx )`. Remove all spaces to compare.
+        let flat: String = list
+            .tokens
+            .to_string()
+            .chars()
+            .filter(|c| !c.is_whitespace())
+            .collect();
+        for (keyword, variant) in [
+            ("allow", MlintLevelOverride::Allow),
+            ("warn", MlintLevelOverride::Warn),
+            ("deny", MlintLevelOverride::Deny),
+        ] {
+            if flat.contains(&format!("{keyword}({lint_name})")) {
+                return Some(variant);
+            }
+        }
+    }
+    None
+}
diff --git a/mingling_cli/src/linter/mlint_report.rs b/mingling_cli/src/linter/mlint_report.rs
new file mode 100644
index 0000000..3c52828
--- /dev/null
+++ b/mingling_cli/src/linter/mlint_report.rs
@@ -0,0 +1,413 @@
+use cargo_metadata::diagnostic::{
+    DiagnosticCodeBuilder, DiagnosticLevel as CargoLevel, DiagnosticSpanBuilder,
+    DiagnosticSpanLineBuilder,
+};
+
+use cargo_metadata::{Message, PackageId};
+
+use annotate_snippets::level::{ERROR, HELP, NOTE, WARNING};
+use annotate_snippets::{AnnotationKind, Group, Renderer, Snippet};
+use mingling::macros::{buffer, chain, pack, r_append, r_eprintln, renderer};
+use mingling::{AnyOutput, ProgramCollect, Routable};
+
+use crate::Next;
+use crate::metadata::setup::ResUsingJson;
+
+/// Complete structure of a Lint report, containing inspection results and associated metadata.
+pub struct MlintReport {
+    /// Source file name
+    pub file_name: String,
+
+    /// Full source text of the file, used to extract line content and compute byte offsets
+    pub source_code: String,
+
+    /// Severity level of the report
+    pub level: MlintLevel,
+
+    /// Name of the Lint
+    pub lint_code: String,
+
+    /// Content of the report
+    pub message: String,
+
+    /// Source code locations
+    pub spans: Vec<LintSpan>,
+
+    /// Attached sub-reports for this report
+    pub attached_reports: Vec<MlintReport>,
+
+    /// Package ID that this report belongs to
+    pub package_id: Option<String>,
+
+    /// Compilation target name that this report belongs to
+    pub target_name: Option<String>,
+
+    /// Compilation target type that this report belongs to
+    pub target_kind: Option<String>,
+
+    /// Compilation target source file path that this report belongs to
+    pub target_src_path: Option<String>,
+}
+
+/// Report severity level, indicating the seriousness of the Lint result.
+#[derive(Clone, Copy, PartialEq, Eq)]
+pub enum MlintLevel {
+    Error,
+    Warning,
+    Note,
+    Help,
+}
+
+/// Source code location span, representing a range of source code and its associated text information.
+pub struct LintSpan {
+    /// Starting line number (1-based)
+    pub line_start: usize,
+    /// Ending line number (1-based)
+    pub line_end: usize,
+    /// Starting column (1-based char offset)
+    pub column_start: usize,
+    /// Ending column (1-based char offset)
+    pub column_end: usize,
+    /// Source lines at this location
+    pub text: Vec<LintSpanLine>,
+    /// Optional label description
+    pub label: Option<String>,
+}
+
+/// A single line of text in a source location with highlight range.
+pub struct LintSpanLine {
+    /// Full source line text (no trailing `\n`)
+    pub text: String,
+    /// Highlight start (1-based char offset)
+    pub highlight_start: usize,
+    /// Highlight end (1-based char offset)
+    pub highlight_end: usize,
+}
+
+impl MlintReport {
+    /// Build a `LintSpan` from a syn spanned item and the source text.
+    pub fn span_from_syn<T: syn::spanned::Spanned>(value: &T, source: &str) -> LintSpan {
+        let span = value.span();
+        let start = span.start();
+        let end = span.end();
+
+        // Extract line content from source
+        let lines: Vec<&str> = source.lines().collect();
+        let text = if start.line == end.line && start.line <= lines.len() {
+            let line_text = lines[start.line.saturating_sub(1)];
+            let hl_start = proc_macro2_byte_col_to_char_1based(line_text, start.column);
+            let hl_end = proc_macro2_byte_col_to_char_1based(line_text, end.column);
+            vec![LintSpanLine {
+                text: line_text.to_string(),
+                highlight_start: hl_start,
+                highlight_end: hl_end,
+            }]
+        } else {
+            // Multi-line: generate line by line
+            (start.line..=end.line.min(lines.len()))
+                .map(|i| {
+                    let line_text = lines[i.saturating_sub(1)];
+                    let (hl_start, hl_end) = if i == start.line {
+                        (
+                            proc_macro2_byte_col_to_char_1based(line_text, start.column),
+                            line_text.chars().count(),
+                        )
+                    } else if i == end.line {
+                        (
+                            1,
+                            proc_macro2_byte_col_to_char_1based(line_text, end.column),
+                        )
+                    } else {
+                        (1, line_text.chars().count())
+                    };
+                    LintSpanLine {
+                        text: line_text.to_string(),
+                        highlight_start: hl_start,
+                        highlight_end: hl_end,
+                    }
+                })
+                .collect::<Vec<_>>()
+        };
+
+        LintSpan {
+            line_start: start.line,
+            line_end: end.line,
+            column_start: proc_macro2_byte_col_to_char_1based(
+                lines.get(start.line.saturating_sub(1)).unwrap_or(&""),
+                start.column,
+            ),
+            column_end: proc_macro2_byte_col_to_char_1based(
+                lines.get(end.line.saturating_sub(1)).unwrap_or(&""),
+                end.column,
+            ),
+            text,
+            label: None,
+        }
+    }
+
+    /// Compute byte offset from (line, column) within source.
+    /// line: 1-based, column: 1-based char offset.
+    pub fn line_col_to_byte_offset(&self, line: usize, col: usize) -> usize {
+        let mut byte_pos = 0usize;
+        for (i, line_str) in self.source_code.lines().enumerate() {
+            if i + 1 == line {
+                return byte_pos + char_1based_to_byte_offset(line_str, col);
+            }
+            byte_pos += line_str.len() + 1; // +1 for \n
+        }
+        self.source_code.len()
+    }
+}
+
+/// proc-macro2's LineColumn.column is **0-based byte offset**.
+/// Convert to 1-based char offset.
+fn proc_macro2_byte_col_to_char_1based(line: &str, byte_col: usize) -> usize {
+    line.char_indices()
+        .position(|(i, _)| i >= byte_col)
+        .map(|pos| pos + 1) // → 1-based
+        .unwrap_or(line.chars().count().max(1))
+}
+
+/// 1-based char offset → byte offset within a string
+fn char_1based_to_byte_offset(s: &str, char_1based: usize) -> usize {
+    s.char_indices()
+        .nth(char_1based.saturating_sub(1))
+        .map(|(i, _)| i)
+        .unwrap_or(s.len())
+}
+
+impl MlintReport {
+    pub fn to_annotate_snippet_render(&self) -> String {
+        let level = mlinit_level_to_annotate(&self.level);
+        let title = level.clone().primary_title(&self.message);
+        // code 不放在 title 里，改放在 note 中
+        let mut group = Group::with_title(title);
+
+        for span in &self.spans {
+            let source = span
+                .text
+                .iter()
+                .map(|l| l.text.as_str())
+                .collect::<Vec<_>>()
+                .join("\n");
+
+            let byte_range = if span.text.len() == 1 {
+                let line = &span.text[0];
+                let start = char_1based_to_byte_offset(&line.text, line.highlight_start);
+                let end = char_1based_to_byte_offset(&line.text, line.highlight_end);
+                start..end
+            } else {
+                let first = &span.text[0];
+                let last = span.text.last().unwrap();
+                let start = char_1based_to_byte_offset(&first.text, first.highlight_start);
+                let prefix_len: usize = span.text[..span.text.len() - 1]
+                    .iter()
+                    .map(|l| l.text.len() + 1)
+                    .sum();
+                let end = prefix_len + char_1based_to_byte_offset(&last.text, last.highlight_end);
+                start..end
+            };
+
+            let mut snippet = Snippet::source(source)
+                .line_start(span.line_start)
+                .path(&self.file_name);
+
+            let annotation = match &span.label {
+                Some(label) => AnnotationKind::Primary
+                    .span(byte_range)
+                    .label(label.as_str()),
+                None => AnnotationKind::Primary.span(byte_range),
+            };
+            snippet = snippet.annotation(annotation);
+            group = group.element(snippet);
+        }
+
+        for child in &self.attached_reports {
+            let child_level = mlinit_level_to_annotate(&child.level);
+            let msg = child_level.clone().message(&child.message);
+            group = group.element(msg);
+        }
+
+        // 添加 note: `#[mlint(level([code]))]` on by default
+        if !self.lint_code.is_empty() {
+            let level_name = match self.level {
+                MlintLevel::Error => "deny",
+                MlintLevel::Warning => "warn",
+                MlintLevel::Note | MlintLevel::Help => "allow",
+            };
+            let note_text = format!(
+                "`#[mlint({level_name}([{}]))]` on by default",
+                self.lint_code
+            );
+            let note_msg = NOTE.clone().message(note_text);
+            group = group.element(note_msg);
+        }
+
+        let renderer = Renderer::styled();
+        renderer.render(&[group])
+    }
+}
+
+fn mlinit_level_to_annotate(level: &MlintLevel) -> &'static annotate_snippets::Level<'static> {
+    match level {
+        MlintLevel::Error => &ERROR,
+        MlintLevel::Warning => &WARNING,
+        MlintLevel::Note => &NOTE,
+        MlintLevel::Help => &HELP,
+    }
+}
+
+impl MlintReport {
+    pub fn to_compiler_message(&self) -> Message {
+        use cargo_metadata::{CompilerMessageBuilder, Edition, TargetBuilder};
+
+        let target_kind_str = self.target_kind.as_deref().unwrap_or("bin");
+        let target_kind_parsed: cargo_metadata::TargetKind = target_kind_str.into();
+        let crate_kind: cargo_metadata::CrateType = target_kind_str.into();
+
+        let target = TargetBuilder::default()
+            .name(self.target_name.as_deref().unwrap_or_default())
+            .kind(vec![target_kind_parsed])
+            .crate_types(vec![crate_kind])
+            .required_features(Vec::<String>::new())
+            .src_path(self.target_src_path.as_deref().unwrap_or_default())
+            .edition(Edition::E2021)
+            .doctest(false)
+            .test(false)
+            .doc(false)
+            .build()
+            .unwrap();
+
+        let diagnostic = self.build_diagnostic(
+            &self.message,
+            &self.lint_code,
+            &self.level,
+            &self.spans,
+            &self.attached_reports,
+        );
+
+        Message::CompilerMessage(
+            CompilerMessageBuilder::default()
+                .package_id(PackageId {
+                    repr: self.package_id.clone().unwrap_or_else(|| "unknown".into()),
+                })
+                .target(target)
+                .message(diagnostic)
+                .build()
+                .unwrap(),
+        )
+    }
+
+    fn build_diagnostic(
+        &self,
+        message: &str,
+        code: &str,
+        level: &MlintLevel,
+        spans: &[LintSpan],
+        children: &[MlintReport],
+    ) -> cargo_metadata::diagnostic::Diagnostic {
+        cargo_metadata::diagnostic::DiagnosticBuilder::default()
+            .message(message)
+            .code(
+                DiagnosticCodeBuilder::default()
+                    .code(code)
+                    .explanation(None)
+                    .build()
+                    .unwrap(),
+            )
+            .level(match level {
+                MlintLevel::Error => CargoLevel::Error,
+                MlintLevel::Warning => CargoLevel::Warning,
+                MlintLevel::Note => CargoLevel::Note,
+                MlintLevel::Help => CargoLevel::Help,
+            })
+            .spans(
+                spans
+                    .iter()
+                    .map(|s| self.lint_span_to_diagnostic_span(s))
+                    .collect::<Vec<_>>(),
+            )
+            .children(
+                children
+                    .iter()
+                    .map(|c| {
+                        self.build_diagnostic(
+                            &c.message,
+                            &c.lint_code,
+                            &c.level,
+                            &c.spans,
+                            &c.attached_reports,
+                        )
+                    })
+                    .collect::<Vec<_>>(),
+            )
+            .rendered(None)
+            .build()
+            .unwrap()
+    }
+
+    fn lint_span_to_diagnostic_span(
+        &self,
+        span: &LintSpan,
+    ) -> cargo_metadata::diagnostic::DiagnosticSpan {
+        let byte_start = self.line_col_to_byte_offset(span.line_start, span.column_start);
+        let byte_end = self.line_col_to_byte_offset(span.line_end, span.column_end);
+
+        DiagnosticSpanBuilder::default()
+            .file_name(&self.file_name)
+            .byte_start(byte_start as u32)
+            .byte_end(byte_end as u32)
+            .line_start(span.line_start)
+            .line_end(span.line_end)
+            .column_start(span.column_start)
+            .column_end(span.column_end)
+            .is_primary(true)
+            .text(
+                span.text
+                    .iter()
+                    .map(|l| {
+                        DiagnosticSpanLineBuilder::default()
+                            .text(&l.text)
+                            .highlight_start(l.highlight_start)
+                            .highlight_end(l.highlight_end)
+                            .build()
+                            .unwrap()
+                    })
+                    .collect::<Vec<_>>(),
+            )
+            .label(span.label.clone())
+            .suggested_replacement(None::<String>)
+            .suggestion_applicability(None::<cargo_metadata::diagnostic::Applicability>)
+            .expansion(None)
+            .build()
+            .unwrap()
+    }
+}
+
+pack!(StateLintReports = Vec<MlintReport>);
+pack!(ResultLintReportsAnnotateSnippet = Vec<MlintReport>);
+pack!(ResultLintReportsJson = Vec<MlintReport>);
+
+#[chain]
+pub fn handle_state_lint_reports(reports: StateLintReports, using_json: &ResUsingJson) -> Next {
+    if using_json.using {
+        ResultLintReportsJson::new(reports.inner).to_render()
+    } else {
+        ResultLintReportsAnnotateSnippet::new(reports.inner).to_render()
+    }
+}
+
+#[renderer(buffer)]
+pub fn render_lint_reports(reports: ResultLintReportsAnnotateSnippet) {
+    for report in reports.inner {
+        r_eprintln!("{}", report.to_annotate_snippet_render());
+    }
+}
+
+#[renderer(buffer)]
+pub fn render_lint_reports_json(reports: ResultLintReportsJson) {
+    for report in reports.inner {
+        // DIRTY: Dispatch to the Message renderer using AnyOutput to obtain the render result and append it to the Buffer
+        r_append!(|| { crate::ThisProgram::render(AnyOutput::new(report.to_compiler_message())) });
+    }
+}
diff --git a/mingling_cli/src/lints.rs b/mingling_cli/src/lints.rs
new file mode 100644
index 0000000..5bed483
--- /dev/null
+++ b/mingling_cli/src/lints.rs
@@ -0,0 +1,61 @@
+#![allow(unused)]
+use crate::linter::mlint_report::{MlintLevel, MlintReport};
+
+mod template_linter;
+pub use template_linter::linter as template_linter;
+mod unnecessary_render_result_creation;
+pub use unnecessary_render_result_creation::linter as unnecessary_render_result_creation;
+
+/// Run all registered lints on a parsed file with its source text.
+pub fn run_all_lints(file: &syn::File, source: &str) -> Vec<MlintReport> {
+    use crate::linter::mlint_attr::{get_mlint_override, MlintLevelOverride};
+    let mut reports = vec![];
+    for item in &file.items {
+        if let syn::Item::Fn(f) = item {
+            // Check item-level #[mlint(allow/warn/deny(template_linter))]
+            let skip = get_mlint_override(&f.attrs, "template_linter") == Some(MlintLevelOverride::Allow);
+            if !skip {
+                let mut rs = template_linter::linter(f.clone(), source);
+                // Apply deny override at item level
+                if get_mlint_override(&f.attrs, "template_linter") == Some(MlintLevelOverride::Deny) {
+                    for r in &mut rs { r.level = MlintLevel::Error; }
+                }
+                reports.extend(rs);
+            }
+            // Check item-level #[mlint(allow/warn/deny(unnecessary_render_result_creation))]
+            let skip = get_mlint_override(&f.attrs, "unnecessary_render_result_creation") == Some(MlintLevelOverride::Allow);
+            if !skip {
+                let mut rs = unnecessary_render_result_creation::linter(f.clone(), source);
+                // Apply deny override at item level
+                if get_mlint_override(&f.attrs, "unnecessary_render_result_creation") == Some(MlintLevelOverride::Deny) {
+                    for r in &mut rs { r.level = MlintLevel::Error; }
+                }
+                reports.extend(rs);
+            }
+
+        }
+    }
+    // Apply file-level #![mlint(allow/warn/deny(...))] overrides
+    for r in &mut reports {
+        let name = &r.lint_code;
+        if let Some(override_level) = get_mlint_override(&file.attrs, name) {
+            match override_level {
+                MlintLevelOverride::Allow => {
+                    // remove by marking; filtered below
+                    r.level = MlintLevel::Help; // sentinel: filtered out
+                }
+                MlintLevelOverride::Deny => {
+                    r.level = MlintLevel::Error;
+                }
+                MlintLevelOverride::Warn => {
+                    if r.level != MlintLevel::Error {
+                        r.level = MlintLevel::Warning;
+                    }
+                }
+            }
+        }
+    }
+    // Remove allowed reports (sentinel = Help)
+    reports.retain(|r| r.level != MlintLevel::Help);
+    reports
+}
\ No newline at end of file
diff --git a/mingling_cli/src/lints/template_linter.rs b/mingling_cli/src/lints/template_linter.rs
new file mode 100644
index 0000000..4ea2f94
--- /dev/null
+++ b/mingling_cli/src/lints/template_linter.rs
@@ -0,0 +1,48 @@
+//! Template Linter
+//!
+//! ## Summary
+//!
+//! This is a template Linter that introduces how to add a Lint for Mingling.
+//! You can write an introduction for this Linter in the Summary section, for example:
+//!
+//! - Trigger conditions
+//! - Why is it necessary?
+//!
+//! ## Metadata
+//!
+//! > This section is the **Metadata** section, which needs to be filled in correctly.
+//! > These contents will eventually be compiled as the Linter's behavior.
+//!
+//! Author: `Weicao-CatilGrass`
+//! Default: `allow`
+//            ^^^^^ Supported parameters: `warn`, `allow`, `deny`
+
+// --- ABOUT AUTO IDENTIFICATION RULES ---
+//
+// The compiler will treat code with the following structure as a Linter entry point:
+//  |
+// --> your_linter_module.rs
+//  |
+//  | pub fn linter(ast: syn::ItemX) -> Vec<MlintReport> {
+//  |     /* ... */      ^^^^^^^^^^ Your linter scope
+//  | }
+//  |
+//  = note: Please ensure your function is `pub`, named `linter`, and returns `Vec<MlintReport>`
+//
+// --- ABOUT AUTO IDENTIFICATION RULES ---
+
+use crate::linter::mlint_report::MlintReport;
+
+pub fn linter(_ast: syn::ItemFn, _source: &str) -> Vec<MlintReport> {
+    //              ^^^^^^^^^^^ Supported parameters:
+    //                               | syn::File
+    //                               | syn::ItemImpl
+    //                               | syn::ItemStruct
+    //                               | syn::ItemEnum
+    //                               | syn::ItemTrait
+    //                               | syn::ItemFn
+    //                               | syn::ItemMacro
+    //                               | syn::ItemMod
+    //                               | syn::ItemUnion
+    vec![]
+}
diff --git a/mingling_cli/src/lints/unnecessary_render_result_creation.rs b/mingling_cli/src/lints/unnecessary_render_result_creation.rs
new file mode 100644
index 0000000..fa6809b
--- /dev/null
+++ b/mingling_cli/src/lints/unnecessary_render_result_creation.rs
@@ -0,0 +1,157 @@
+//! Unnecessary Manual RenderResult Creation
+//!
+//! ## Summary
+//!
+//! Detects `#[renderer]` functions that manually create a `RenderResult` and
+//! manage it via `r_println!(r, ...)` style calls, when they could be simplified
+//! to `#[renderer(buffer)]` which handles the buffer automatically.
+//!
+//! This lint will not trigger if `r` is used outside of `r_println!`,
+//! `r_eprintln!`, `r_print`, `r_eprint`, or `r_append`.
+//!
+//! ## Metadata
+//!
+//! Author: `Weicao-CatilGrass`
+//! Default: `warn`
+
+use crate::linter::mlint_report::{MlintLevel, MlintReport};
+
+pub fn linter(ast: syn::ItemFn, source: &str) -> Vec<MlintReport> {
+    if !has_renderer_attr(&ast) {
+        return vec![];
+    }
+
+    let stmts = &ast.block.stmts;
+    if stmts.len() < 2 {
+        return vec![];
+    }
+
+    let (r_ident, let_idx) = match find_render_result_new(stmts) {
+        Some(pair) => pair,
+        None => return vec![],
+    };
+
+    let r_name = r_ident.to_string();
+    let mut only_print_and_return = true;
+    let mut print_count = 0;
+
+    for stmt in &stmts[let_idx + 1..] {
+        if !check_stmt_usage(stmt, &r_name, &mut print_count) {
+            only_print_and_return = false;
+            break;
+        }
+    }
+
+    if only_print_and_return && print_count > 0 {
+        let span = MlintReport::span_from_syn(&ast.sig, source);
+        vec![MlintReport {
+            file_name: String::new(),
+            source_code: source.to_string(),
+            level: MlintLevel::Warning,
+            lint_code: "unnecessary_render_result_creation".into(),
+            message: format!(
+                "unnecessary manual `RenderResult` creation in `{}`: use `#[renderer(buffer)]` instead",
+                ast.sig.ident,
+            ),
+            spans: vec![span],
+            attached_reports: vec![MlintReport {
+                file_name: String::new(),
+                source_code: String::new(),
+                level: MlintLevel::Help,
+                lint_code: String::new(),
+                message: "change to `#[renderer(buffer)]` and use `r_println!(...)` without the `r` parameter".into(),
+                spans: vec![],
+                attached_reports: vec![],
+                package_id: None,
+                target_name: None,
+                target_kind: None,
+                target_src_path: None,
+            }],
+            package_id: None,
+            target_name: None,
+            target_kind: None,
+            target_src_path: None,
+        }]
+    } else {
+        vec![]
+    }
+}
+
+fn has_renderer_attr(func: &syn::ItemFn) -> bool {
+    func.attrs.iter().any(|a| {
+        if !a.path().is_ident("renderer") {
+            return false;
+        }
+        if let Ok(list) = a.meta.require_list() {
+            let tokens = list.tokens.to_string();
+            if tokens.contains("buffer") {
+                return false;
+            }
+        }
+        true
+    })
+}
+
+fn find_render_result_new(stmts: &[syn::Stmt]) -> Option<(proc_macro2::Ident, usize)> {
+    for (i, stmt) in stmts.iter().enumerate() {
+        if let syn::Stmt::Local(local) = stmt
+            && let Some(init) = &local.init
+            && let syn::Pat::Ident(pat_id) = &local.pat
+            && pat_id.mutability.is_some()
+            && let syn::Expr::Call(call) = &*init.expr
+            && let syn::Expr::Path(expr_path) = call.func.as_ref()
+        {
+            let segs = &expr_path.path.segments;
+            let matches = match segs.len() {
+                2 => segs[0].ident == "RenderResult" && segs[1].ident == "new",
+                3 => {
+                    segs[0].ident == "mingling"
+                        && segs[1].ident == "RenderResult"
+                        && segs[2].ident == "new"
+                }
+                _ => false,
+            };
+            if matches {
+                return Some((pat_id.ident.clone(), i));
+            }
+        }
+    }
+    None
+}
+
+fn check_stmt_usage(stmt: &syn::Stmt, r_name: &str, print_count: &mut usize) -> bool {
+    // return r; → allowed
+    if let syn::Stmt::Expr(expr, _) = stmt
+        && let syn::Expr::Return(ret) = expr
+        && let Some(ret_expr) = &ret.expr
+        && let syn::Expr::Path(p) = ret_expr.as_ref()
+        && p.path.is_ident(r_name)
+    {
+        return true;
+    }
+
+    // r_println!(r, ...) → allowed
+    if let syn::Stmt::Macro(stmt_mac) = stmt {
+        let macro_name = stmt_mac
+            .mac
+            .path
+            .segments
+            .last()
+            .map(|s| s.ident.to_string())
+            .unwrap_or_default();
+        let is_r_macro = matches!(
+            macro_name.as_str(),
+            "r_println" | "r_eprintln" | "r_print" | "r_eprint" | "r_append"
+        );
+        if is_r_macro
+            && let Some(first_arg) = stmt_mac.mac.tokens.clone().into_iter().next()
+            && first_arg.to_string() == *r_name
+        {
+            *print_count += 1;
+            return true;
+        }
+    }
+
+    let s = format!("{stmt:#?}");
+    !s.contains(&format!("\"{r_name}\""))
+}
diff --git a/mingling_cli/src/main.rs b/mingling_cli/src/main.rs
index 59fa92d..c822a12 100644
--- a/mingling_cli/src/main.rs
+++ b/mingling_cli/src/main.rs
@@ -1,28 +1,29 @@
 use crate::{linter::MinglingLinterSetup, metadata::MinglingMetadataSetup};
 use mingling::{
     macros::gen_program,
-    setup::{
-        ExitCodeSetup,
-        picker::{HelpFlagSetup, StructuralRendererSetup},
-    },
+    setup::{ExitCodeSetup, picker::HelpFlagSetup},
 };
 
+pub mod diagnostic;
+pub mod errors;
 pub mod linter;
+pub mod lints;
+pub mod message;
 pub mod metadata;
 
-fn main() {
+#[tokio::main]
+async fn main() {
     let mut program = ThisProgram::new();
 
     // Setups
     program.with_setup(HelpFlagSetup::default());
     program.with_setup(ExitCodeSetup::default());
-    program.with_setup(StructuralRendererSetup);
 
     program.with_setup(MinglingMetadataSetup);
     program.with_setup(MinglingLinterSetup);
 
     // Exec
-    program.exec_and_exit();
+    program.exec_and_exit().await;
 }
 
 gen_program!();
diff --git a/mingling_cli/src/message.rs b/mingling_cli/src/message.rs
new file mode 100644
index 0000000..3e50c30
--- /dev/null
+++ b/mingling_cli/src/message.rs
@@ -0,0 +1,10 @@
+use cargo_metadata::Message;
+use mingling::macros::{buffer, group, r_println, renderer, renderify};
+
+group!(Message);
+
+#[renderer(buffer, renderify)]
+pub fn render_message(msg: Message) {
+    let r = serde_json::to_string(&msg)?;
+    r_println!("{}", r);
+}
diff --git a/mingling_cli/src/metadata.rs b/mingling_cli/src/metadata.rs
index 0c0b0bf..2e7aeef 100644
--- a/mingling_cli/src/metadata.rs
+++ b/mingling_cli/src/metadata.rs
@@ -1,4 +1,8 @@
-use mingling::{Program, macros::program_setup};
+use cargo_metadata::Metadata;
+use mingling::{
+    Program,
+    macros::{buffer, group, program_setup, r_println, renderer, renderify},
+};
 
 use crate::metadata::{cmd_metadata::CMDMetadata, setup::CargoMetadataSetup};
 
@@ -10,3 +14,11 @@ pub fn mingling_metadata_setup(program: &mut Program<crate::ThisProgram>) {
     program.with_setup(CargoMetadataSetup);
     program.with_dispatcher(CMDMetadata);
 }
+
+group!(Metadata);
+
+#[renderer(buffer, renderify)]
+pub fn render_metadata(metadata: Metadata) {
+    let result = serde_json::to_string(&metadata)?;
+    r_println!("{}", result);
+}
diff --git a/mingling_cli/src/metadata/cmd_metadata.rs b/mingling_cli/src/metadata/cmd_metadata.rs
index 867e606..18241a2 100644
--- a/mingling_cli/src/metadata/cmd_metadata.rs
+++ b/mingling_cli/src/metadata/cmd_metadata.rs
@@ -1,16 +1,17 @@
+use cargo_metadata::Metadata;
 use mingling::{
     LazyRes,
-    macros::{chain, dispatcher, pack_structural},
+    macros::{chain, dispatcher, pack},
 };
 
 use crate::metadata::setup::ResMetadata;
 
 dispatcher!("metadata");
 
-pack_structural!(ResultMetadata = ResMetadata);
+pack!(ResultMetadata = ResMetadata);
 
 #[chain]
-pub fn handle_metadata(_: EntryMetadata, metadata: &mut LazyRes<ResMetadata>) -> ResultMetadata {
+pub fn handle_metadata(_: EntryMetadata, metadata: &mut LazyRes<ResMetadata>) -> Metadata {
     let metadata = metadata.get_ref().clone();
-    ResultMetadata::new(metadata)
+    metadata.data().clone()
 }
diff --git a/mingling_cli/src/metadata/setup.rs b/mingling_cli/src/metadata/setup.rs
index 4a891b6..198baf1 100644
--- a/mingling_cli/src/metadata/setup.rs
+++ b/mingling_cli/src/metadata/setup.rs
@@ -3,7 +3,6 @@ use std::{env::current_dir, path::PathBuf};
 use cargo_metadata::{CargoOpt, MetadataCommand};
 use mingling::{
     LazyInit, Program,
-    consts::REMAINS,
     macros::program_setup,
     picker::{IntoPicker, value::Flag},
     prelude::*,
@@ -16,11 +15,28 @@ pub const CARGO_TOML: &str = "Cargo.toml";
 use cargo_metadata::Metadata;
 use serde::Serialize;
 
+/// Resource holding parsed `cargo metadata` output.
+///
+/// This is lazily initialized during program setup by calling `cargo metadata`
+/// with the appropriate CLI flags (e.g., `--features`, `--all-features`,
+/// `--no-default-features`, `--no-deps`, `--message-format`).
+///
+/// Access the inner [`Metadata`] via [`ResMetadata::data()`], which panics if
+/// called before initialization (guaranteed not to happen in normal usage).
 #[derive(Default, Clone, Serialize)]
 pub struct ResMetadata {
     data: Option<Metadata>,
 }
 
+/// Resource indicating whether the output format is JSON.
+///
+/// Set to `true` when `--message-format json` (or similar) is passed.
+/// Used by renderers to decide whether to serialize structs as JSON.
+#[derive(Default, Clone, Serialize)]
+pub struct ResUsingJson {
+    pub using: bool,
+}
+
 impl ResMetadata {
     /// Returns a reference to the parsed `cargo metadata`.
     ///
@@ -38,7 +54,8 @@ impl ResMetadata {
 
 #[program_setup]
 pub fn cargo_metadata_setup(program: &mut Program<crate::ThisProgram>) {
-    let args = program.take_args();
+    let args = program.get_args().to_vec();
+
     let (
         feature_args,
         manifest_path,
@@ -46,7 +63,6 @@ pub fn cargo_metadata_setup(program: &mut Program<crate::ThisProgram>) {
         enable_all_features,
         no_default_features,
         no_deps,
-        args,
     ) = args
         .pick(&arg![features: Vec<String>])
         .pick(&arg![manifest_path: Option<String>])
@@ -54,12 +70,12 @@ pub fn cargo_metadata_setup(program: &mut Program<crate::ThisProgram>) {
         .pick(&arg![all_features: Flag])
         .pick(&arg![no_default_features: Flag])
         .pick(&arg![no_deps: Flag])
-        .pick(&REMAINS)
         .unwrap();
-    program.replace_args(args.into());
 
-    // Bind format setting to StructuralRenderer
-    program.structural_renderer_name = message_format.into();
+    // Is Using Json
+    program.with_resource(ResUsingJson {
+        using: message_format.contains("json"),
+    });
 
     // Current Dir
     let current_dir = current_dir().unwrap();