feat: Improve CLI output and warning messages

* feat: Add progress indicator and improve CLI usability

This commit introduces several improvements to the user experience of the privlog CLI.

- A progress indicator is now displayed by default during the scanning process to provide better feedback and prevent the appearance of a hanging process.

- The --verbose flag now controls the verbosity of the underlying semgrep scanner, providing more detailed output for debugging.

- The check subcommand has been merged into the main privlog command to simplify usage and align with the documentation.

- A --version flag has been added to display the current version of the tool.

- A CHANGELOG.md has been created to document changes for future releases.

* chore: Bump version to 0.2.2

* feat: Improve AST-based warnings for sensitive data

The AST checker now provides more informative warnings by including the name of the sensitive identifier that was detected.

Previously, the warning was a generic message:
"Sensitive identifier passed to log. Hash/pseudonymize or omit."

Now, it will include the variable name, for example:
'Sensitive identifier "user_email" passed to log. Hash, pseudonymize, or omit before logging.'

This makes it easier for developers to quickly identify and remediate the issue.

* fix: Add python version classifiers to pyproject.toml

Adds classifiers for Python 3.9 through 3.12 to resolve the 'python missing' badge on PyPI and in the README.

* docs: Update examples to reflect new output style

The examples in the README and the GitHub Pages index.html have been updated to show the new, more informative warning message that includes the name of the sensitive identifier.

Author: aureliuscanon

CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.2] - 2026-03-11
+
+### Added
+- Progress indicator during the AST scan when using the `--verbose` flag, showing which file is being scanned.
+- `--version` flag to display the current version of the tool.
+- Verbose output for scanning stages, making it clear when `semgrep` and `AST` scans are running.
+
+### Changed
+- Improved AST check warnings to include the name of the sensitive identifier found, making it easier to locate and fix issues. For example, the warning for `PL2101` will now be `Sensitive identifier "user_email" passed to log...`.
+- The progress indicator and scanning stage messages are now shown by default to provide better feedback during scans. The `--verbose` flag now only controls the verbosity of the underlying `semgrep` tool.
+- The `check` subcommand has been merged into the main `privlog` command. This simplifies the command-line usage from `privlog check` to `privlog` and aligns the tool's behavior with the `README.md` documentation.

README.md

@@ -29,7 +29,7 @@ def reauthenticate_user(user_email):
 Running `privlog .` will produce the following error:
 
 ```
-app/auth.py:5:5 [ERROR]    PL2101 Sensitive identifier passed to log. Hash/pseudonymize or omit.
+app/auth.py:5:5 [ERROR]    PL2101 Sensitive identifier "user_email" passed to log. Hash, pseudonymize, or omit before logging.
 ```
 
 ## Features
@@ -99,6 +99,11 @@ privlog -w .
 
 This will display all findings, color-coded by severity, but will still only fail the build if `ERROR`s are present.
 
+### Other Flags
+
+- `--verbose` / `-v`: Enables verbose output from the underlying `semgrep` scanner. This is useful for debugging rules and understanding which files `semgrep` is scanning or skipping. By default, `privlog` always shows a high-level progress indicator; this flag provides much more detail about the `semgrep` scanning phase.
+- `--version`: Display the installed version of `privlog`.
+
 ### Configuring Custom Wrappers
 
 You can teach `privlog` to recognize your own custom logging functions. In your project's `pyproject.toml` file, add a `[tool.privlog.custom_wrappers]` section.
@@ -120,7 +125,7 @@ log_event = { details = "WARNING" }
 
 ## Status
 
-Privlog is currently in early development (v0.2.1).
+Privlog is currently in early development (v0.2.2).
 Feedback and contributions are welcome.
 
 ---

docs/index.html

@@ -157,7 +157,7 @@ <h2>What it checks</h2>
 
     <section class="card">
       <h2>Example</h2>
-      <pre><code>app.py:12:9 [ERROR] PL2101 Sensitive identifier passed to log. Hash/pseudonymize or omit.</code></pre>
+      <pre><code>app.py:12:9 [ERROR] PL2101 Sensitive identifier "user_email" passed to log. Hash, pseudonymize, or omit before logging.</code></pre>
     </section>
 
     <section class="card">

privlog/ast_checks.py

@@ -3,6 +3,7 @@
 import ast
 from dataclasses import dataclass
 from pathlib import Path
+import typer
 
 # A forward declaration is needed for the type hint in this file
 class PrivlogConfig: ...
@@ -92,10 +93,10 @@ def _is_safe_wrapper(expr: ast.AST) -> bool:
     )
 
 
-def _get_expr_sensitivity(expr: ast.AST) -> str | None:
+def _get_expr_sensitivity(expr: ast.AST) -> tuple[str, str] | None:
     """
     Checks an expression for sensitive names.
-    Returns severity ('ERROR', 'WARNING') or None if not sensitive.
+    Returns a tuple of (severity, sensitive_name) or None if not sensitive.
     """
     # Allow slicing, which is a form of truncation
     if isinstance(expr, ast.Subscript):
@@ -105,17 +106,19 @@ def _get_expr_sensitivity(expr: ast.AST) -> str | None:
     if _is_safe_wrapper(expr):
         return None
 
-    # Allow known-safe name variables
     names = _names_in_expr(expr)
+    # Allow known-safe name variables
     if any(n in SAFE_NAMES for n in names):
         return None
 
     # Flag if any sensitive name appears
-    if any(n.lower() in HIGH_CONFIDENCE_SENSITIVE_NAMES for n in names):
-        return "ERROR"
-    
-    if any(n.lower() in WARNING_SENSITIVE_NAMES for n in names):
-        return "WARNING"
+    for name in names:
+        if name.lower() in HIGH_CONFIDENCE_SENSITIVE_NAMES:
+            return "ERROR", name
+            
+    for name in names:
+        if name.lower() in WARNING_SENSITIVE_NAMES:
+            return "WARNING", name
 
     return None
 
@@ -177,11 +180,13 @@ def visit_Call(self, node: ast.Call) -> None:
                     args_to_check.extend(node.args[1:])
 
             for arg in args_to_check:
-                severity = _get_expr_sensitivity(arg)
-                if severity:
+                sensitivity = _get_expr_sensitivity(arg)
+                if sensitivity:
+                    severity, name = sensitivity
                     code = "PL2301" if is_print else "PL2101"
                     call_type = "print()" if is_print else "log"
-                    self._add_finding(node, code, f"Sensitive identifier passed to {call_type}. Hash/pseudonymize or omit.", severity)
+                    message = f'Sensitive identifier "{name}" passed to {call_type}. Hash, pseudonymize, or omit before logging.'
+                    self._add_finding(node, code, message, severity)
                     break
 
         # Check 2: Heuristic checks for dictionary/object logging
@@ -223,15 +228,31 @@ def visit_Call(self, node: ast.Call) -> None:
     ".git",
 }
 
+def _collect_python_files(root: Path) -> list[Path]:
+    """Recursively finds all Python files in a directory, respecting ignores."""
+    all_files = []
+    for py in root.rglob("*.py"):
+        if any(part in DEFAULT_IGNORE_DIRS for part in py.parts):
+            continue
+        all_files.append(py)
+    return all_files
+
+
 def run_ast_checks(root: Path, config: PrivlogConfig) -> list[AstFinding]:
+    """
+    Scans for sensitive data in Python files using AST checks.
+    """
     findings: list[AstFinding] = []
 
-    all_python_files = root.rglob("*.py")
+    files_to_scan = _collect_python_files(root)
+    total_files = len(files_to_scan)
 
-    for py in all_python_files:
-        # Check if any parent directory component is in the ignore list
-        if any(part in DEFAULT_IGNORE_DIRS for part in py.parts):
-            continue
+    typer.secho(f"Running AST checks on {total_files} Python files...", fg=typer.colors.BLUE)
+
+    for i, py in enumerate(files_to_scan):
+        # \r to return to start of line, \x1b[K to clear line
+        progress_msg = f"Scanning [{i + 1}/{total_files}] {str(py)}"
+        typer.secho(f"\r\x1b[K{progress_msg}", fg=typer.colors.WHITE, nl=False)
 
         try:
             text = py.read_text(encoding="utf-8", errors="replace")
@@ -240,6 +261,12 @@ def run_ast_checks(root: Path, config: PrivlogConfig) -> list[AstFinding]:
             v.visit(tree)
             findings.extend(v.findings)
         except SyntaxError:
-            # Ignore files that aren't parseable in current context
             continue
+        except Exception:
+            # Fallback for other file-read errors
+            continue
+    
+    # Clear the line and print a final message
+    typer.secho("\r\x1b[KAST checks complete.", fg=typer.colors.BLUE)
+
     return findings

privlog/cli.py

@@ -1,25 +1,41 @@
 import typer
 from pathlib import Path
+from typing import Optional
+import importlib.metadata
 from privlog.runner import run_analysis
 from privlog.formatter import print_findings
 
-app = typer.Typer(add_completion=False, no_args_is_help=True)
+__version__ = "0.2.2"
 
-@app.command()
-def check(
-    path: Path = typer.Argument(Path("."), exists=True),
+def version_callback(value: bool):
+    if value:
+        typer.echo(f"privlog version {__version__}")
+        raise typer.Exit()
+
+app = typer.Typer(add_completion=False, no_args_is_help=False)
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    path: Path = typer.Argument(Path("."), exists=True, help="Path to scan."),
     config: Path = typer.Option(None, "--config", "-c", help="Optional privlog config YAML"),
     rules: Path = typer.Option(None, "--rules", "-r", help="Override rules file/folder"),
     json: bool = typer.Option(False, "--json", help="Output JSON (raw Semgrep)"),
-    verbose: bool = typer.Option(False, "--verbose", help="Verbose output"),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Verbose output"),
     warnings: bool = typer.Option(
         False, "--warnings", "-w", help="Show WARNING findings in addition to ERRORs."
     ),
+    version: Optional[bool] = typer.Option(
+        None, "--version", callback=version_callback, is_eager=True, help="Show the version and exit."
+    ),
 ):
     """
     Run privlog checks on a codebase path.
     Exits non-zero if ERROR violations are found.
     """
+    if ctx.invoked_subcommand is not None:
+        return  # Should not happen with a single command, but good practice
+
     result = run_analysis(path=path, config=config, rules=rules, verbose=verbose)
 
     if json:
@@ -29,13 +45,10 @@ def check(
         if not warnings:
             findings_to_print = [f for f in result.findings if f.severity == "ERROR"]
 
-        # If there are findings, but none to print (because they are warnings),
-        # give a specific success message.
         if result.findings and not findings_to_print:
             typer.secho("✅ privlog passed. No errors found.", fg=typer.colors.GREEN)
             typer.secho("  (Warnings were found. Run with -w to show them)")
         else:
             print_findings(findings_to_print)
 
-    # The exit code from run_analysis is now based on ERROR-level findings only
     raise typer.Exit(code=result.exit_code)

privlog/runner.py

@@ -5,6 +5,7 @@
 from dataclasses import dataclass, field
 from pathlib import Path
 from importlib.resources import files
+import typer
 
 # Use tomllib for Python 3.11+, otherwise tomli
 try:
@@ -84,7 +85,8 @@ def _run_semgrep(path: Path, config: Path | None, rules: Path | None, verbose: b
     if verbose:
         cmd.insert(1, "--verbose")
 
-    proc = subprocess.run(cmd, capture_output=True, text=True, encoding="utf-8")
+    stderr_setting = None if verbose else subprocess.PIPE
+    proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=stderr_setting, text=True, encoding="utf-8")
     raw = proc.stdout.strip() if proc.stdout else ""
 
     findings: list[Finding] = []
@@ -118,7 +120,12 @@ def run_analysis(path: Path, config: Path | None, rules: Path | None, verbose: b
     # Load config from the target path
     privlog_config = _load_config(path)
 
+    typer.secho("Running Semgrep scan...", fg=typer.colors.BLUE)
+
     semgrep_result = _run_semgrep(path, config, rules, verbose)
+
+    typer.secho("Semgrep scan complete.", fg=typer.colors.BLUE)
+
     ast_findings = run_ast_checks(path, privlog_config)
 
     # Convert AST findings to the common Finding type

pyproject.toml

@@ -4,14 +4,21 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "privlog"
-version = "0.2.1"
+version = "0.2.2"
 description = "Privacy-aware logging hygiene linter for Python"
 readme = "README.md"
 requires-python = ">=3.9"
 authors = [
   {name="Christopher Mariani"}
 ]
 license = { text = "MIT" }
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+]
 dependencies = [
   "typer>=0.12.0",
   "PyYAML>=6.0.0",