feat: env 소스 주석 fix 추가

Author: JeremyDev87

crates/maximus-checks/src/env.rs

@@ -5,14 +5,28 @@ use std::process::Command;
 
 use maximus_core::{
     is_concrete_env_file_name, is_template_env_file_name, looks_like_secret, make_finding,
-    parse_env, plan_create_env_example, plan_sync_env_example, read_text_if_exists,
-    render_env_template, sort_findings, unique_fixes, FileKind, FindingInput, FixPlan, ProjectFile,
-    ProjectSnapshot, Severity,
+    parse_env, plan_create_env_example, plan_create_env_example_with_groups, plan_sync_env_example,
+    plan_sync_env_example_with_groups, read_text_if_exists, render_env_template,
+    render_env_template_groups, sort_findings, unique_fixes, EnvTemplateRenderOptions,
+    EnvTemplateSourceGroup, FileKind, FindingInput, FixPlan, ProjectFile, ProjectSnapshot,
+    Severity,
 };
 
 use crate::check_outcome::CheckOutcome;
 
 pub fn run_env_check(project: &ProjectSnapshot) -> io::Result<CheckOutcome> {
+    run_env_check_with_options(project, &EnvCheckOptions::default())
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub struct EnvCheckOptions {
+    pub template_render: EnvTemplateRenderOptions,
+}
+
+pub fn run_env_check_with_options(
+    project: &ProjectSnapshot,
+    options: &EnvCheckOptions,
+) -> io::Result<CheckOutcome> {
     let mut findings = Vec::new();
     let mut fixes = Vec::new();
     let mut planned_fixes = Vec::new();
@@ -112,6 +126,8 @@ pub fn run_env_check(project: &ProjectSnapshot) -> io::Result<CheckOutcome> {
             .filter(|record| is_concrete_env_file_name(&record.file.name))
             .collect::<Vec<_>>();
         let contract_keys = collect_contract_keys(&concrete_records);
+        let contract_groups =
+            collect_contract_groups(&project.root_dir, &concrete_records, &contract_keys);
 
         let gitignore_sources =
             read_ancestor_gitignore_sources(&gitignore_traversal_root, &directory.dir)?;
@@ -176,11 +192,20 @@ pub fn run_env_check(project: &ProjectSnapshot) -> io::Result<CheckOutcome> {
                 ),
                 files: vec![output_path],
             });
-            planned_fixes.push(plan_create_env_example(
-                &project.root_dir,
-                &directory.dir,
-                &contract_keys,
-            ));
+            if options.template_render.source_comments {
+                planned_fixes.push(plan_create_env_example_with_groups(
+                    &project.root_dir,
+                    &directory.dir,
+                    contract_groups.clone(),
+                    options.template_render.clone(),
+                ));
+            } else {
+                planned_fixes.push(plan_create_env_example(
+                    &project.root_dir,
+                    &directory.dir,
+                    &contract_keys,
+                ));
+            }
         }
 
         if let Some(example_record) = example_record {
@@ -223,12 +248,27 @@ pub fn run_env_check(project: &ProjectSnapshot) -> io::Result<CheckOutcome> {
                     ),
                     files: vec![example_record.file.path.clone()],
                 });
-                planned_fixes.push(plan_sync_env_example(
-                    &project.root_dir,
-                    &example_record.file.path,
-                    &example_record.parsed_source_text,
-                    &missing_keys,
-                ));
+                if options.template_render.source_comments {
+                    let missing_groups = collect_contract_groups(
+                        &project.root_dir,
+                        &concrete_records,
+                        &missing_keys,
+                    );
+                    planned_fixes.push(plan_sync_env_example_with_groups(
+                        &project.root_dir,
+                        &example_record.file.path,
+                        &example_record.parsed_source_text,
+                        missing_groups,
+                        options.template_render.clone(),
+                    ));
+                } else {
+                    planned_fixes.push(plan_sync_env_example(
+                        &project.root_dir,
+                        &example_record.file.path,
+                        &example_record.parsed_source_text,
+                        &missing_keys,
+                    ));
+                }
             }
 
             for contract_record in &contract_records {
@@ -367,6 +407,29 @@ pub fn render_synced_env_example(existing_text: &str, missing_keys: &[String]) -
     format!("{existing_text}{prefix}{addition}")
 }
 
+pub fn render_created_env_example_with_sources(groups: Vec<EnvTemplateSourceGroup>) -> String {
+    render_env_template_groups(
+        groups,
+        &EnvTemplateRenderOptions {
+            source_comments: true,
+        },
+    )
+}
+
+pub fn render_synced_env_example_with_sources(
+    existing_text: &str,
+    groups: Vec<EnvTemplateSourceGroup>,
+) -> String {
+    let prefix = if existing_text.ends_with('\n') || existing_text.is_empty() {
+        ""
+    } else {
+        "\n"
+    };
+    let addition = render_created_env_example_with_sources(groups);
+
+    format!("{existing_text}{prefix}{addition}")
+}
+
 #[derive(Debug, Clone)]
 struct ParsedEnvRecord {
     file: ProjectFile,
@@ -389,6 +452,37 @@ fn collect_contract_keys(records: &[&ParsedEnvRecord]) -> Vec<String> {
     keys
 }
 
+fn collect_contract_groups(
+    root_dir: &Path,
+    records: &[&ParsedEnvRecord],
+    selected_keys: &[String],
+) -> Vec<EnvTemplateSourceGroup> {
+    let selected = selected_keys.iter().cloned().collect::<BTreeSet<_>>();
+    let mut seen = BTreeSet::new();
+    let mut groups = Vec::new();
+
+    for record in records {
+        let keys = record
+            .parsed
+            .order
+            .iter()
+            .filter(|key| selected.contains(*key) && seen.insert((*key).clone()))
+            .cloned()
+            .collect::<Vec<_>>();
+
+        if keys.is_empty() {
+            continue;
+        }
+
+        groups.push(EnvTemplateSourceGroup {
+            source: Some(relative_display_path(root_dir, &record.file.path)),
+            keys,
+        });
+    }
+
+    groups
+}
+
 fn relative_display_path(root_dir: &Path, target: &Path) -> String {
     root_dir
         .strip_prefix(root_dir)

crates/maximus-checks/src/lib.rs

@@ -17,7 +17,11 @@ mod workspace_config;
 
 pub use check_outcome::CheckOutcome;
 pub use config_duplicates::run_config_duplicate_check;
-pub use env::{render_created_env_example, render_synced_env_example, run_env_check};
+pub use env::{
+    render_created_env_example, render_created_env_example_with_sources, render_synced_env_example,
+    render_synced_env_example_with_sources, run_env_check, run_env_check_with_options,
+    EnvCheckOptions,
+};
 pub use eslint_prettier::run_eslint_prettier_check;
 pub use jsx_config::run_jsx_config_check;
 pub use module_system::run_module_system_check;

crates/maximus-checks/tests/env_checks.rs

@@ -7,8 +7,15 @@ mod check_outcome;
 #[path = "../src/env.rs"]
 mod env;
 
-use env::{render_created_env_example, render_synced_env_example, run_env_check};
-use maximus_core::{apply_fix, discover_project, FixOperation, FixPlan, Severity};
+use env::{
+    render_created_env_example, render_created_env_example_with_sources, render_synced_env_example,
+    render_synced_env_example_with_sources, run_env_check, run_env_check_with_options,
+    EnvCheckOptions,
+};
+use maximus_core::{
+    apply_fix, discover_project, EnvTemplateRenderOptions, EnvTemplateSourceGroup, FixOperation,
+    FixPlan, Severity,
+};
 use tempfile::TempDir;
 
 #[test]
@@ -515,11 +522,12 @@ fn env_sync_planned_fix_uses_audited_snapshot_text() {
     match &planned.operation {
         FixOperation::SyncEnvExample {
             existing_text,
-            missing_keys,
+            groups,
             ..
         } => {
             assert_eq!(existing_text, "PRIMARY=\n");
-            assert_eq!(missing_keys, &vec!["SECONDARY".to_string()]);
+            assert_eq!(groups.len(), 1);
+            assert_eq!(groups[0].keys, vec!["SECONDARY".to_string()]);
         }
         _ => panic!("expected sync env example operation"),
     }
@@ -560,6 +568,84 @@ fn env_example_render_helpers_match_js_create_and_sync_semantics() {
     );
 }
 
+#[test]
+fn env_example_source_comment_helpers_group_and_sort_opt_in_output() {
+    let groups = vec![
+        EnvTemplateSourceGroup {
+            source: Some(".env.local".to_string()),
+            keys: vec!["LOCAL_Z".to_string(), "LOCAL_A".to_string()],
+        },
+        EnvTemplateSourceGroup {
+            source: Some(".env".to_string()),
+            keys: vec![
+                "BASE_Z".to_string(),
+                "BASE_A".to_string(),
+                "BASE_A".to_string(),
+            ],
+        },
+    ];
+
+    assert_eq!(
+        render_created_env_example_with_sources(groups.clone()),
+        "# Source: .env\nBASE_A=\nBASE_Z=\n\n# Source: .env.local\nLOCAL_A=\nLOCAL_Z=\n"
+    );
+    assert_eq!(
+        render_synced_env_example_with_sources("EXISTING=", groups),
+        "EXISTING=\n# Source: .env\nBASE_A=\nBASE_Z=\n\n# Source: .env.local\nLOCAL_A=\nLOCAL_Z=\n"
+    );
+}
+
+#[test]
+fn env_source_comment_option_changes_planned_fix_output_without_default_regression() {
+    let fixture = TempDir::new().expect("temp dir should exist");
+    write(
+        fixture.path().join(".env.local"),
+        "LOCAL_Z=1\nLOCAL_A=2\nSHARED=local\n",
+    );
+    write(
+        fixture.path().join(".env"),
+        "BASE_Z=1\nBASE_A=2\nSHARED=base\n",
+    );
+
+    let project = discover_project(fixture.path()).expect("project should discover");
+    let default_outcome = run_env_check(&project).expect("default check should run");
+    let default_fix = default_outcome
+        .planned_fixes
+        .first()
+        .expect("default planned fix should exist")
+        .clone();
+    apply_fix(&default_fix).expect("default fix should apply");
+    let default_output = fs::read_to_string(fixture.path().join(".env.example"))
+        .expect("default example should exist");
+    assert_eq!(
+        default_output,
+        "BASE_A=\nBASE_Z=\nLOCAL_A=\nLOCAL_Z=\nSHARED=\n"
+    );
+
+    fs::remove_file(fixture.path().join(".env.example")).expect("example should remove");
+    let opt_in_outcome = run_env_check_with_options(
+        &project,
+        &EnvCheckOptions {
+            template_render: EnvTemplateRenderOptions {
+                source_comments: true,
+            },
+        },
+    )
+    .expect("opt-in check should run");
+    let opt_in_fix = opt_in_outcome
+        .planned_fixes
+        .first()
+        .expect("opt-in planned fix should exist")
+        .clone();
+    apply_fix(&opt_in_fix).expect("opt-in fix should apply");
+    let opt_in_output = fs::read_to_string(fixture.path().join(".env.example"))
+        .expect("opt-in example should exist");
+    assert_eq!(
+        opt_in_output,
+        "# Source: .env\nBASE_A=\nBASE_Z=\nSHARED=\n\n# Source: .env.local\nLOCAL_A=\nLOCAL_Z=\n"
+    );
+}
+
 #[test]
 fn env_contract_matrix_fixtures_cover_template_variants_and_duplicate_chains() {
     let matrix_root = fixture_root("env-contract-matrix");

crates/maximus-cli/src/args.rs

@@ -5,6 +5,7 @@ use std::fmt::{Display, Formatter};
 pub struct Flags {
     pub diff: bool,
     pub dry_run: bool,
+    pub env_source_comments: bool,
     pub fail_on: Option<String>,
     pub fix_ids: Vec<String>,
     pub fix_prefixes: Vec<String>,
@@ -74,6 +75,7 @@ where
         match token.to_str() {
             Some("--diff") => flags.diff = true,
             Some("--dry-run") => flags.dry_run = true,
+            Some("--env-source-comments") => flags.env_source_comments = true,
             Some("--fail-on") => {
                 let value = next_option_value(tokens.next(), "--fail-on")?;
                 flags.fail_on = Some(value.to_string_lossy().into_owned());
@@ -218,6 +220,7 @@ mod tests {
                 flags: Flags {
                     diff: false,
                     dry_run: true,
+                    env_source_comments: false,
                     fail_on: None,
                     fix_ids: Vec::new(),
                     fix_prefixes: Vec::new(),
@@ -250,6 +253,7 @@ mod tests {
             "env,tsconfig",
             "--skip",
             "duplicates",
+            "--env-source-comments",
             "--fail-on",
             "error",
             "--fix-id",
@@ -271,6 +275,7 @@ mod tests {
             Some(vec!["duplicates".to_string()])
         );
         assert_eq!(parsed.flags.fail_on.as_deref(), Some("error"));
+        assert!(parsed.flags.env_source_comments);
         assert_eq!(
             parsed.flags.fix_ids,
             vec!["env-example:create:.".to_string()]