docs: update project description to reflect insight features

Author: DropFan

.github/workflows/release.yml

@@ -180,7 +180,7 @@ jobs:
         run: |
           cat > homebrew-tap/Formula/codelens.rb << 'FORMULA'
           class Codelens < Formula
-            desc "High performance code statistics tool written in Rust"
+            desc "High performance code analysis tool — stats, health scores, hotspots, and trends"
             homepage "https://github.com/DropFan/codelens"
             version "VERSION_PLACEHOLDER"
             license "MIT"

README.md

@@ -1,6 +1,6 @@
 # Codelens
 
-High performance code statistics tool written in Rust.
+High performance code analysis tool written in Rust — stats, health scores, hotspots, and trends.
 
 ## Features
 
@@ -9,6 +9,9 @@ High performance code statistics tool written in Rust.
 - **Smart Filtering**: Respects `.gitignore`, auto-excludes build directories
 - **Multiple Outputs**: Console, JSON, CSV, Markdown, HTML with charts
 - **Complexity Analysis**: Function count, cyclomatic complexity, nesting depth
+- **Health Score**: Project/directory/file-level health grading (A-F) with pluggable scoring models
+- **Hotspot Detection**: Identify risky files via churn × complexity analysis
+- **Trend Tracking**: Save snapshots and compare codebase evolution over time
 - **Extensible**: Add custom languages via TOML configuration
 
 ## Installation
@@ -61,6 +64,37 @@ codelens --exclude vendor,dist,node_modules
 codelens --list-languages
 ```
 
+### Health Score
+
+Score code health across five dimensions (complexity, function size, comment ratio, file size, nesting depth) with grades from A to F.
+
+```bash
+codelens health .               # Project, directory, and file-level report
+codelens health . --top 20      # Show top 20 worst files
+codelens health . -f json       # Output as JSON
+```
+
+### Hotspot Detection
+
+Find the riskiest files by combining git change frequency (churn) with code complexity — files that change often AND are complex are the most likely sources of bugs.
+
+```bash
+codelens hotspot .              # Last 90 days (default)
+codelens hotspot . --since 30d  # Last 30 days
+codelens hotspot . --since 6m --top 5  # Last 6 months, top 5
+```
+
+### Trend Tracking
+
+Save snapshots and compare codebase evolution over time. Snapshots are stored in `.codelens/snapshots/`. Use `latest`, `latest~N`, or a date prefix like `2025-01-01` as references.
+
+```bash
+codelens trend --save --label v1.0     # Save a labeled snapshot
+codelens trend                         # Compare latest two snapshots
+codelens trend --list                  # List all snapshots
+codelens trend --compare latest~2 latest  # Compare specific snapshots
+```
+
 ## Output Formats
 
 | Format | Flag | Description |

crates/codelens-core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "codelens-core"
-description = "Core library for codelens - high performance code statistics tool"
+description = "Core library for codelens - high performance code analysis tool"
 version.workspace = true
 edition.workspace = true
 rust-version.workspace = true

crates/codelens-core/src/lib.rs

@@ -1,6 +1,6 @@
 //! # codelens-core
 //!
-//! Core library for codelens - a high performance code statistics tool.
+//! Core library for codelens - a high performance code analysis tool.
 //!
 //! ## Features
 //!

crates/codelens-core/templates/report.html

@@ -230,7 +230,7 @@ <h2>By Language</h2>
         </section>
 
         <footer>
-            <p>Generated by <strong>Codelens</strong> in {{ elapsed_secs }}s | High-performance code statistics tool powered by Rust</p>
+            <p>Generated by <strong>Codelens</strong> in {{ elapsed_secs }}s | High-performance code analysis tool powered by Rust</p>
         </footer>
     </div>
 

crates/codelens/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "codelens"
-description = "High performance code statistics tool written in Rust"
+description = "High performance code analysis tool — stats, health scores, hotspots, and trends"
 version.workspace = true
 edition.workspace = true
 rust-version.workspace = true

crates/codelens/src/cli.rs

@@ -11,13 +11,13 @@ const STYLES: Styles = Styles::styled()
     .literal(AnsiColor::Cyan.on_default().effects(Effects::BOLD))
     .placeholder(AnsiColor::Cyan.on_default());
 
-/// High performance code statistics tool.
+/// High performance code analysis tool.
 #[derive(Parser, Debug)]
 #[command(
     name = "codelens",
     author,
     version,
-    about = "High performance code statistics tool",
+    about = "High performance code analysis tool — stats, health scores, hotspots, and trends",
     styles = STYLES,
     after_help = EXAMPLES,
 )]
@@ -42,10 +42,20 @@ pub struct Cli {
 #[derive(Subcommand, Debug)]
 pub enum Command {
     /// Analyze code health score.
+    #[command(long_about = "Score code health across five dimensions: complexity, function size, \
+        comment ratio, file size, and nesting depth. Reports at project, directory, and file \
+        levels with grades from A (best) to F (worst). Use --top to control how many items \
+        are shown per level.")]
     Health(HealthArgs),
     /// Detect change hotspots (churn x complexity).
+    #[command(long_about = "Find the riskiest files in your codebase by combining git change \
+        frequency (churn) with code complexity. Files that change often AND are complex are \
+        the most likely sources of bugs. Requires a git repository.")]
     Hotspot(HotspotArgs),
     /// Track codebase trends with snapshots.
+    #[command(long_about = "Save snapshots of codebase metrics and compare them over time. \
+        Snapshots are stored in .codelens/snapshots/ as JSON files. References: \"latest\", \
+        \"latest~N\" (Nth before latest), or date prefix like \"2025-01-01\".")]
     Trend(TrendArgs),
 }
 

crates/codelens/src/main.rs

@@ -1,4 +1,4 @@
-//! Codelens CLI - High performance code statistics tool.
+//! Codelens CLI - High performance code analysis tool.
 
 mod cli;
 

docs/RELEASE.md

@@ -230,7 +230,7 @@ cargo install codelens
 Formula 模板 (`codelens.rb`):
 ```ruby
 class Codelens < Formula
-  desc "High performance code statistics tool"
+  desc "High performance code analysis tool — stats, health scores, hotspots, and trends"
   homepage "https://github.com/DropFan/codelens"
   version "0.1.0"
   license "MIT"

templates/report.html

@@ -230,7 +230,7 @@ <h2>By Language</h2>
         </section>
 
         <footer>
-            <p>Generated by <strong>Codelens</strong> in {{ elapsed_secs }}s | High-performance code statistics tool powered by Rust</p>
+            <p>Generated by <strong>Codelens</strong> in {{ elapsed_secs }}s | High-performance code analysis tool powered by Rust</p>
         </footer>
     </div>