Feat: declutter artifact (#15)

* feat: updatd cli to show artifacts on demand

* docs: updated artifact

* refactor: rename --artifact to --show-artifacts for clarity

- Renamed CLI option to avoid confusion with --artifacts/--no-artifacts
- Updated documentation with new flag name
- Added test coverage for show_artifact_details parameter

Author: mahimairaja

docs/reference/commands.md

@@ -12,6 +12,7 @@ Scans a path for Python environments and Python artifacts, then prints the full
 | `--stale-days` |  | `90` | Days threshold for stale marking |
 | `--include-dotenv` |  | `false` | Include plain `.env` directories |
 | `--artifacts/--no-artifacts` |  | `true` | Enable/disable Python artifact detection |
+| `--show-artifacts` | `-a` | `false` | Show detailed artifact-level sections in report output |
 | `--path-mode` |  | `name` | Path column rendering: `name`, `relative`, `absolute` |
 | `--rich` |  | `false` | Use rich-rendered output |
 
@@ -20,6 +21,8 @@ Examples:
 ```bash
 envoic scan .
 envoic scan ~/projects --deep
+envoic scan ~/projects --deep --show-artifacts
+envoic scan ~/projects --deep -a
 envoic scan ~/projects --no-artifacts
 envoic scan . --json
 envoic scan . --path-mode relative

src/envoic/cli.py

@@ -150,6 +150,12 @@ def scan(
         "--artifacts/--no-artifacts",
         help="Include Python artifact detection.",
     ),
+    show_artifacts: bool = typer.Option(
+        False,
+        "--show-artifacts",
+        "-a",
+        help="Show detailed artifact-level report sections.",
+    ),
     path_mode: PathMode = typer.Option(
         "name",
         "--path-mode",
@@ -174,7 +180,12 @@ def scan(
         raise typer.Exit(0)
 
     _print_output(
-        format_report(result, path_mode=path_mode, deep=deep),
+        format_report(
+            result,
+            path_mode=path_mode,
+            deep=deep,
+            show_artifact_details=show_artifacts,
+        ),
         use_rich=rich_output,
     )
 

src/envoic/report.py

@@ -169,6 +169,7 @@ def format_report(
     title: str = "ENVOIC - Python Environment Report",
     path_mode: PathMode = "name",
     deep: bool = False,
+    show_artifact_details: bool = False,
 ) -> str:
     stale_count = sum(1 for env in result.environments if env.is_stale)
     artifact_count = sum(item.count for item in result.artifact_summary)
@@ -217,40 +218,49 @@ def format_report(
 
     lines.append("─" * 58)
     lines.append("")
-    lines.append("ARTIFACTS")
-    lines.append("─" * 58)
-    lines.append(_artifact_table_header(deep))
-    lines.append("─" * 58)
-    if not result.artifact_summary:
-        lines.append("  (no artifacts found)")
-    else:
-        for summary in result.artifact_summary:
-            lines.append(_artifact_row(summary, deep=deep))
-    lines.append("─" * 58)
-    if deep and any(
-        item.safety == SafetyLevel.CAREFUL for item in result.artifact_summary
-    ):
-        careful_patterns = {
-            item.pattern
-            for item in result.artifact_summary
-            if item.safety == SafetyLevel.CAREFUL
-        }
-        for pattern in sorted(careful_patterns):
-            note = CAREFUL_NOTES.get(pattern)
-            if note:
-                lines.append(f"  * {pattern}: {note}")
+    if show_artifact_details:
+        lines.append("ARTIFACTS")
         lines.append("─" * 58)
-    if not deep:
-        lines.append("  (run with --deep to include size data)")
+        lines.append(_artifact_table_header(deep))
         lines.append("─" * 58)
-    lines.append("")
-    lines.append(
-        _artifact_distribution(
-            result.artifact_summary,
-            deep=deep,
+        if not result.artifact_summary:
+            lines.append("  (no artifacts found)")
+        else:
+            for summary in result.artifact_summary:
+                lines.append(_artifact_row(summary, deep=deep))
+        lines.append("─" * 58)
+        if deep and any(
+            item.safety == SafetyLevel.CAREFUL for item in result.artifact_summary
+        ):
+            careful_patterns = {
+                item.pattern
+                for item in result.artifact_summary
+                if item.safety == SafetyLevel.CAREFUL
+            }
+            for pattern in sorted(careful_patterns):
+                note = CAREFUL_NOTES.get(pattern)
+                if note:
+                    lines.append(f"  * {pattern}: {note}")
+            lines.append("─" * 58)
+        if not deep:
+            lines.append("  (run with --deep to include size data)")
+            lines.append("─" * 58)
+        lines.append("")
+        lines.append(
+            _artifact_distribution(
+                result.artifact_summary,
+                deep=deep,
+            )
         )
-    )
-    lines.append("")
+        lines.append("")
+    else:
+        lines.append("ARTIFACT DETAILS")
+        lines.append("─" * 58)
+        lines.append(
+            "  (hidden by default; run with --artifact to show detailed breakdown)"
+        )
+        lines.append("─" * 58)
+        lines.append("")
     lines.append(
         _size_distribution(
             result.environments, path_mode=path_mode, base_path=result.scan_path

tests/test_report.py

@@ -85,3 +85,54 @@ def test_format_list_relative_paths() -> None:
     text = format_list([env], path_mode="relative", base_path=Path("/tmp"))
     assert "project" in text
     assert "project/.venv" not in text
+
+
+def test_format_report_show_artifact_details_false() -> None:
+    """Test that artifact details are hidden by default."""
+    env = EnvInfo(
+        path=Path("/tmp/project/.venv"),
+        env_type=EnvType.VENV,
+        python_version="3.12.1",
+        size_bytes=1024 * 1024,
+        modified=datetime.now(UTC),
+    )
+    result = ScanResult(
+        scan_path=Path("/tmp"),
+        scan_depth=5,
+        duration_seconds=1.2,
+        environments=[env],
+        total_size_bytes=1024 * 1024,
+        hostname="host-a",
+        timestamp=datetime(2026, 2, 9, 12, 0, 0, tzinfo=UTC),
+    )
+
+    text = format_report(result, show_artifact_details=False)
+
+    assert "ARTIFACT DETAILS" in text
+    assert "hidden by default" in text
+    assert "run with --show-artifacts" in text.lower() or "run with --artifact" in text.lower()
+
+
+def test_format_report_show_artifact_details_true() -> None:
+    """Test that artifact details are shown when flag is enabled."""
+    env = EnvInfo(
+        path=Path("/tmp/project/.venv"),
+        env_type=EnvType.VENV,
+        python_version="3.12.1",
+        size_bytes=1024 * 1024,
+        modified=datetime.now(UTC),
+    )
+    result = ScanResult(
+        scan_path=Path("/tmp"),
+        scan_depth=5,
+        duration_seconds=1.2,
+        environments=[env],
+        total_size_bytes=1024 * 1024,
+        hostname="host-a",
+        timestamp=datetime(2026, 2, 9, 12, 0, 0, tzinfo=UTC),
+    )
+
+    text = format_report(result, show_artifact_details=True)
+
+    assert "ARTIFACTS" in text
+    assert "hidden by default" not in text