pysentry-rs 0.2.1__tar.gz → 0.2.2__tar.gz

{pysentry_rs-0.2.1 → pysentry_rs-0.2.2}/Cargo.lock

@@ -150,6 +150,15 @@ version = "2.9.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1b8e56985ec62d17e9c1001dc89c88ecd7dc08e47eba5ec7c29c7b5eeecde967"
 
+[[package]]
+name = "block-buffer"
+version = "0.10.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71"
+dependencies = [
+ "generic-array",
+]
+
 [[package]]
 name = "bumpalo"
 version = "3.19.0"
@@ -250,6 +259,15 @@ version = "0.8.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
 
+[[package]]
+name = "cpufeatures"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280"
+dependencies = [
+ "libc",
+]
+
 [[package]]
 name = "crc32fast"
 version = "1.5.0"
@@ -259,6 +277,16 @@ dependencies = [
  "cfg-if",
 ]
 
+[[package]]
+name = "crypto-common"
+version = "0.1.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1bfb12502f3fc46cca1bb51ac28df9d618d813cdc3d2f25b9fe775a34af26bb3"
+dependencies = [
+ "generic-array",
+ "typenum",
+]
+
 [[package]]
 name = "derive_arbitrary"
 version = "1.4.1"
@@ -270,6 +298,16 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "digest"
+version = "0.10.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
+dependencies = [
+ "block-buffer",
+ "crypto-common",
+]
+
 [[package]]
 name = "dirs"
 version = "6.0.0"
@@ -448,6 +486,16 @@ dependencies = [
  "slab",
 ]
 
+[[package]]
+name = "generic-array"
+version = "0.14.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a"
+dependencies = [
+ "typenum",
+ "version_check",
+]
+
 [[package]]
 name = "getrandom"
 version = "0.2.16"
@@ -1067,7 +1115,7 @@ dependencies = [
 
 [[package]]
 name = "pysentry"
-version = "0.2.1"
+version = "0.2.2"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -1078,10 +1126,12 @@ dependencies = [
  "futures",
  "pep440_rs",
  "pyo3",
+ "regex",
  "reqwest",
  "serde",
  "serde_json",
  "serde_yaml",
+ "sha2",
  "tempfile",
  "thiserror",
  "tokio",
@@ -1438,6 +1488,17 @@ dependencies = [
  "unsafe-libyaml",
 ]
 
+[[package]]
+name = "sha2"
+version = "0.10.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"
+dependencies = [
+ "cfg-if",
+ "cpufeatures",
+ "digest",
+]
+
 [[package]]
 name = "sharded-slab"
 version = "0.1.7"
@@ -1826,6 +1887,12 @@ version = "0.2.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b"
 
+[[package]]
+name = "typenum"
+version = "1.18.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1dccffe3ce07af9386bfd29e80c0ab1a8205a2fc34e4bcd40364df902cfa8f3f"
+
 [[package]]
 name = "unicode-ident"
 version = "1.0.18"
@@ -1891,6 +1958,12 @@ version = "0.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ba73ea9cf16a25df0c8caa16c51acb937d5712a8429db78a3ee29d5dcacd3a65"
 
+[[package]]
+name = "version_check"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
+
 [[package]]
 name = "want"
 version = "0.3.1"

{pysentry_rs-0.2.1 → pysentry_rs-0.2.2}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "pysentry"
-version = "0.2.1"
+version = "0.2.2"
 edition = "2021"
 rust-version = "1.79"
 description = "Security vulnerability auditing for Python packages"
@@ -31,10 +31,12 @@ fs-err = "3.1.1"
 futures = "0.3.31"
 pep440_rs = "0.7.3"
 pyo3 = { version = "0.25.1", features = ["extension-module"], optional = true }
+regex = "1.11.1"
 reqwest = { version = "0.12.22", features = ["json", "stream", "rustls-tls"], default-features = false }
 serde = { version = "1.0.219", features = ["derive"] }
 serde_json = "1.0.142"
 serde_yaml = "0.9.34"
+sha2 = "0.10.9"
 tempfile = "3.20.0"
 thiserror = "2.0.12"
 tokio = { version = "1.47.1", features = ["fs", "io-util", "rt-multi-thread", "macros", "process"] }

{pysentry_rs-0.2.1 → pysentry_rs-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pysentry-rs
-Version: 0.2.1
+Version: 0.2.2
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
@@ -48,7 +48,7 @@ PySentry audits Python projects for known security vulnerabilities by analyzing
 - **Performance Focused**:
   - Written in Rust for speed
   - Async/concurrent processing
-  - Intelligent caching system
+  - Multi-tier intelligent caching (vulnerability data + resolved dependencies)
 - **Comprehensive Filtering**:
   - Severity levels (low, medium, high, critical)
   - Dependency scopes (main only vs all [optional, dev, prod, etc] dependencies)
@@ -254,6 +254,12 @@ pysentry /path/to/project
 
 # Debug requirements.txt resolution
 pysentry --verbose --resolver uv /path/to/project
+
+# Use longer resolution cache TTL (48 hours)
+pysentry --resolution-cache-ttl 48 /path/to/project
+
+# Clear resolution cache before scanning
+pysentry --clear-resolution-cache /path/to/project
 ```
 
 ### CI/CD Integration Examples
@@ -273,42 +279,115 @@ pysentry --format markdown --output SECURITY-REPORT.md
 
 # Comprehensive audit with all sources and full reporting
 pysentry --sources pypa,pypi,osv --all-extras --format json --fail-on low
+
+# CI environment with fresh resolution cache
+pysentry --clear-resolution-cache --sources pypa,osv --format sarif
+
+# CI with resolution cache disabled
+pysentry --no-resolution-cache --format json --output security-report.json
 ```
 
 ## Configuration
 
 ### Command Line Options
 
-| Option           | Description                                             | Default             |
-| ---------------- | ------------------------------------------------------- | ------------------- |
-| `--format`       | Output format: `human`, `json`, `sarif`, `markdown`     | `human`             |
-| `--severity`     | Minimum severity: `low`, `medium`, `high`, `critical`   | `low`               |
-| `--fail-on`      | Fail (exit non-zero) on vulnerabilities ≥ severity      | `medium`            |
-| `--sources`      | Vulnerability sources: `pypa`, `pypi`, `osv` (multiple) | `pypa`              |
-| `--all-extras`   | Include all dependencies (main + dev + optional)        | `false`             |
-| `--direct-only`  | Check only direct dependencies                          | `false`             |
-| `--ignore`       | Vulnerability IDs to ignore (repeatable)                | `[]`                |
-| `--output`       | Output file path                                        | `stdout`            |
-| `--no-cache`     | Disable caching                                         | `false`             |
-| `--cache-dir`    | Custom cache directory                                  | `~/.cache/pysentry` |
-| `--verbose`      | Enable verbose output                                   | `false`             |
-| `--quiet`        | Suppress non-error output                               | `false`             |
-| `--resolver`     | Dependency resolver: `auto`, `uv`, `pip-tools`          | `auto`              |
-| `--requirements` | Additional requirements files (repeatable)              | `[]`                |
+| Option                     | Description                                             | Default           |
+| -------------------------- | ------------------------------------------------------- | ----------------- |
+| `--format`                 | Output format: `human`, `json`, `sarif`, `markdown`     | `human`           |
+| `--severity`               | Minimum severity: `low`, `medium`, `high`, `critical`   | `low`             |
+| `--fail-on`                | Fail (exit non-zero) on vulnerabilities ≥ severity      | `medium`          |
+| `--sources`                | Vulnerability sources: `pypa`, `pypi`, `osv` (multiple) | `pypa`            |
+| `--all-extras`             | Include all dependencies (main + dev + optional)        | `false`           |
+| `--direct-only`            | Check only direct dependencies                          | `false`           |
+| `--ignore`                 | Vulnerability IDs to ignore (repeatable)                | `[]`              |
+| `--output`                 | Output file path                                        | `stdout`          |
+| `--no-cache`               | Disable all caching                                     | `false`           |
+| `--cache-dir`              | Custom cache directory                                  | Platform-specific |
+| `--resolution-cache-ttl`   | Resolution cache TTL in hours                           | `24`              |
+| `--no-resolution-cache`    | Disable resolution caching only                         | `false`           |
+| `--clear-resolution-cache` | Clear resolution cache on startup                       | `false`           |
+| `--verbose`                | Enable verbose output                                   | `false`           |
+| `--quiet`                  | Suppress non-error output                               | `false`           |
+| `--resolver`               | Dependency resolver: `auto`, `uv`, `pip-tools`          | `auto`            |
+| `--requirements`           | Additional requirements files (repeatable)              | `[]`              |
 
 ### Cache Management
 
-PySentry uses an intelligent caching system to avoid redundant API calls:
+PySentry uses an intelligent multi-tier caching system for optimal performance:
+
+#### Vulnerability Data Cache
+
+- **Location**: `{CACHE_DIR}/pysentry/vulnerability-db/`
+- **Purpose**: Caches vulnerability databases from PyPA, PyPI, OSV
+- **TTL**: 24 hours (configurable per source)
+- **Benefits**: Avoids redundant API calls and downloads
+
+#### Resolution Cache
+
+- **Location**: `{CACHE_DIR}/pysentry/dependency-resolution/`
+- **Purpose**: Caches resolved dependencies from `uv`/`pip-tools`
+- **TTL**: 24 hours (configurable via `--resolution-cache-ttl`)
+- **Benefits**: Dramatically speeds up repeated scans of requirements.txt files
+- **Cache Key**: Based on requirements content, resolver version, Python version, platform
+
+#### Platform-Specific Cache Locations
+
+- **Linux**: `~/.cache/pysentry/`
+- **macOS**: `~/Library/Caches/pysentry/`
+- **Windows**: `%LOCALAPPDATA%\pysentry\`
+
+**Finding Your Cache Location**: Run with `--verbose` to see the actual cache directory path being used.
+
+#### Cache Features
 
-- **Default Location**: `~/.cache/pysentry/` (or system temp directory)
-- **TTL-based Expiration**: Separate expiration for each vulnerability source
 - **Atomic Updates**: Prevents cache corruption during concurrent access
 - **Custom Location**: Use `--cache-dir` to specify alternative location
+- **Selective Clearing**: Control caching behavior per cache type
+- **Content-based Invalidation**: Automatic cache invalidation on content changes
 
-To clear the cache:
+#### Cache Control Examples
 
 ```bash
+# Disable all caching
+pysentry --no-cache
+
+# Disable only resolution caching (keep vulnerability cache)
+pysentry --no-resolution-cache
+
+# Set resolution cache TTL to 48 hours
+pysentry --resolution-cache-ttl 48
+
+# Clear resolution cache on startup (useful for CI)
+pysentry --clear-resolution-cache
+
+# Custom cache directory
+pysentry --cache-dir /tmp/my-pysentry-cache
+```
+
+To manually clear all caches:
+
+```bash
+# Linux
 rm -rf ~/.cache/pysentry/
+
+# macOS
+rm -rf ~/Library/Caches/pysentry/
+
+# Windows (PowerShell)
+Remove-Item -Recurse -Force "$env:LOCALAPPDATA\pysentry"
+```
+
+To clear only resolution cache:
+
+```bash
+# Linux
+rm -rf ~/.cache/pysentry/dependency-resolution/
+
+# macOS
+rm -rf ~/Library/Caches/pysentry/dependency-resolution/
+
+# Windows (PowerShell)
+Remove-Item -Recurse -Force "$env:LOCALAPPDATA\pysentry\dependency-resolution"
 ```
 
 ## Supported Project Formats
@@ -437,26 +516,28 @@ Compatible with GitHub Security tab, VS Code, and other security tools.
 
 PySentry is designed for speed and efficiency:
 
-- **Concurrent Processing**: Vulnerability data fetched in parallel
-- **Smart Caching**: Reduces API calls and parsing overhead
+- **Concurrent Processing**: Vulnerability data fetched in parallel from multiple sources
+- **Multi-tier Caching**: Intelligent caching for both vulnerability data and resolved dependencies
 - **Efficient Matching**: In-memory indexing for fast vulnerability lookups
 - **Streaming**: Large databases processed without excessive memory usage
 
+### Resolution Cache Performance
+
+The resolution cache provides dramatic performance improvements for requirements.txt files:
+
+- **First scan**: Standard resolution time using `uv` or `pip-tools`
+- **Subsequent scans**: Near-instantaneous when cache is fresh (>90% time savings)
+- **Cache invalidation**: Automatic when requirements content, resolver, or environment changes
+- **Content-aware**: Different cache entries for different Python versions and platforms
+
 ### Requirements.txt Resolution Performance
 
-PySentry leverages external resolvers for optimal performance:
+PySentry leverages external resolvers with intelligent caching:
 
 - **uv resolver**: 2-10x faster than pip-tools, handles large dependency trees efficiently
 - **pip-tools resolver**: Reliable fallback, slower but widely compatible
 - **Isolated execution**: Prevents project pollution while maintaining security
-
-### Benchmarks
-
-Typical performance on a project with 100+ dependencies:
-
-- **Cold cache**: 15-30 seconds
-- **Warm cache**: 2-5 seconds
-- **Memory usage**: ~50MB peak
+- **Resolution caching**: Eliminates repeated resolver calls for unchanged requirements
 
 ## Development
 
@@ -581,12 +662,43 @@ ls uv.lock poetry.lock pyproject.toml
 **Performance Issues**
 
 ```bash
-# Clear cache and retry
-rm -rf ~/.cache/pysentry
+# Clear all caches and retry
+rm -rf ~/.cache/pysentry      # Linux
+rm -rf ~/Library/Caches/pysentry  # macOS
+pysentry
+
+# Clear only resolution cache (if vulnerability cache is working)
+rm -rf ~/.cache/pysentry/dependency-resolution/      # Linux
+rm -rf ~/Library/Caches/pysentry/dependency-resolution/  # macOS
 pysentry
 
+# Clear resolution cache via CLI
+pysentry --clear-resolution-cache
+
 # Use verbose mode to identify bottlenecks
 pysentry --verbose
+
+# Disable caching to isolate issues
+pysentry --no-cache
+```
+
+**Resolution Cache Issues**
+
+```bash
+# Clear stale resolution cache after environment changes
+pysentry --clear-resolution-cache
+
+# Disable resolution cache if causing issues
+pysentry --no-resolution-cache
+
+# Extend cache TTL for stable environments
+pysentry --resolution-cache-ttl 168  # 1 week
+
+# Check cache usage with verbose output
+pysentry --verbose  # Shows cache hits/misses
+
+# Force fresh resolution (ignores cache)
+pysentry --clear-resolution-cache --no-resolution-cache
 ```
 
 ## Acknowledgments

{pysentry_rs-0.2.1 → pysentry_rs-0.2.2}/README.md

@@ -22,7 +22,7 @@ PySentry audits Python projects for known security vulnerabilities by analyzing
 - **Performance Focused**:
   - Written in Rust for speed
   - Async/concurrent processing
-  - Intelligent caching system
+  - Multi-tier intelligent caching (vulnerability data + resolved dependencies)
 - **Comprehensive Filtering**:
   - Severity levels (low, medium, high, critical)
   - Dependency scopes (main only vs all [optional, dev, prod, etc] dependencies)
@@ -228,6 +228,12 @@ pysentry /path/to/project
 
 # Debug requirements.txt resolution
 pysentry --verbose --resolver uv /path/to/project
+
+# Use longer resolution cache TTL (48 hours)
+pysentry --resolution-cache-ttl 48 /path/to/project
+
+# Clear resolution cache before scanning
+pysentry --clear-resolution-cache /path/to/project
 ```
 
 ### CI/CD Integration Examples
@@ -247,42 +253,115 @@ pysentry --format markdown --output SECURITY-REPORT.md
 
 # Comprehensive audit with all sources and full reporting
 pysentry --sources pypa,pypi,osv --all-extras --format json --fail-on low
+
+# CI environment with fresh resolution cache
+pysentry --clear-resolution-cache --sources pypa,osv --format sarif
+
+# CI with resolution cache disabled
+pysentry --no-resolution-cache --format json --output security-report.json
 ```
 
 ## Configuration
 
 ### Command Line Options
 
-| Option           | Description                                             | Default             |
-| ---------------- | ------------------------------------------------------- | ------------------- |
-| `--format`       | Output format: `human`, `json`, `sarif`, `markdown`     | `human`             |
-| `--severity`     | Minimum severity: `low`, `medium`, `high`, `critical`   | `low`               |
-| `--fail-on`      | Fail (exit non-zero) on vulnerabilities ≥ severity      | `medium`            |
-| `--sources`      | Vulnerability sources: `pypa`, `pypi`, `osv` (multiple) | `pypa`              |
-| `--all-extras`   | Include all dependencies (main + dev + optional)        | `false`             |
-| `--direct-only`  | Check only direct dependencies                          | `false`             |
-| `--ignore`       | Vulnerability IDs to ignore (repeatable)                | `[]`                |
-| `--output`       | Output file path                                        | `stdout`            |
-| `--no-cache`     | Disable caching                                         | `false`             |
-| `--cache-dir`    | Custom cache directory                                  | `~/.cache/pysentry` |
-| `--verbose`      | Enable verbose output                                   | `false`             |
-| `--quiet`        | Suppress non-error output                               | `false`             |
-| `--resolver`     | Dependency resolver: `auto`, `uv`, `pip-tools`          | `auto`              |
-| `--requirements` | Additional requirements files (repeatable)              | `[]`                |
+| Option                     | Description                                             | Default           |
+| -------------------------- | ------------------------------------------------------- | ----------------- |
+| `--format`                 | Output format: `human`, `json`, `sarif`, `markdown`     | `human`           |
+| `--severity`               | Minimum severity: `low`, `medium`, `high`, `critical`   | `low`             |
+| `--fail-on`                | Fail (exit non-zero) on vulnerabilities ≥ severity      | `medium`          |
+| `--sources`                | Vulnerability sources: `pypa`, `pypi`, `osv` (multiple) | `pypa`            |
+| `--all-extras`             | Include all dependencies (main + dev + optional)        | `false`           |
+| `--direct-only`            | Check only direct dependencies                          | `false`           |
+| `--ignore`                 | Vulnerability IDs to ignore (repeatable)                | `[]`              |
+| `--output`                 | Output file path                                        | `stdout`          |
+| `--no-cache`               | Disable all caching                                     | `false`           |
+| `--cache-dir`              | Custom cache directory                                  | Platform-specific |
+| `--resolution-cache-ttl`   | Resolution cache TTL in hours                           | `24`              |
+| `--no-resolution-cache`    | Disable resolution caching only                         | `false`           |
+| `--clear-resolution-cache` | Clear resolution cache on startup                       | `false`           |
+| `--verbose`                | Enable verbose output                                   | `false`           |
+| `--quiet`                  | Suppress non-error output                               | `false`           |
+| `--resolver`               | Dependency resolver: `auto`, `uv`, `pip-tools`          | `auto`            |
+| `--requirements`           | Additional requirements files (repeatable)              | `[]`              |
 
 ### Cache Management
 
-PySentry uses an intelligent caching system to avoid redundant API calls:
+PySentry uses an intelligent multi-tier caching system for optimal performance:
+
+#### Vulnerability Data Cache
+
+- **Location**: `{CACHE_DIR}/pysentry/vulnerability-db/`
+- **Purpose**: Caches vulnerability databases from PyPA, PyPI, OSV
+- **TTL**: 24 hours (configurable per source)
+- **Benefits**: Avoids redundant API calls and downloads
+
+#### Resolution Cache
+
+- **Location**: `{CACHE_DIR}/pysentry/dependency-resolution/`
+- **Purpose**: Caches resolved dependencies from `uv`/`pip-tools`
+- **TTL**: 24 hours (configurable via `--resolution-cache-ttl`)
+- **Benefits**: Dramatically speeds up repeated scans of requirements.txt files
+- **Cache Key**: Based on requirements content, resolver version, Python version, platform
+
+#### Platform-Specific Cache Locations
+
+- **Linux**: `~/.cache/pysentry/`
+- **macOS**: `~/Library/Caches/pysentry/`
+- **Windows**: `%LOCALAPPDATA%\pysentry\`
+
+**Finding Your Cache Location**: Run with `--verbose` to see the actual cache directory path being used.
+
+#### Cache Features
 
-- **Default Location**: `~/.cache/pysentry/` (or system temp directory)
-- **TTL-based Expiration**: Separate expiration for each vulnerability source
 - **Atomic Updates**: Prevents cache corruption during concurrent access
 - **Custom Location**: Use `--cache-dir` to specify alternative location
+- **Selective Clearing**: Control caching behavior per cache type
+- **Content-based Invalidation**: Automatic cache invalidation on content changes
 
-To clear the cache:
+#### Cache Control Examples
 
 ```bash
+# Disable all caching
+pysentry --no-cache
+
+# Disable only resolution caching (keep vulnerability cache)
+pysentry --no-resolution-cache
+
+# Set resolution cache TTL to 48 hours
+pysentry --resolution-cache-ttl 48
+
+# Clear resolution cache on startup (useful for CI)
+pysentry --clear-resolution-cache
+
+# Custom cache directory
+pysentry --cache-dir /tmp/my-pysentry-cache
+```
+
+To manually clear all caches:
+
+```bash
+# Linux
 rm -rf ~/.cache/pysentry/
+
+# macOS
+rm -rf ~/Library/Caches/pysentry/
+
+# Windows (PowerShell)
+Remove-Item -Recurse -Force "$env:LOCALAPPDATA\pysentry"
+```
+
+To clear only resolution cache:
+
+```bash
+# Linux
+rm -rf ~/.cache/pysentry/dependency-resolution/
+
+# macOS
+rm -rf ~/Library/Caches/pysentry/dependency-resolution/
+
+# Windows (PowerShell)
+Remove-Item -Recurse -Force "$env:LOCALAPPDATA\pysentry\dependency-resolution"
 ```
 
 ## Supported Project Formats
@@ -411,26 +490,28 @@ Compatible with GitHub Security tab, VS Code, and other security tools.
 
 PySentry is designed for speed and efficiency:
 
-- **Concurrent Processing**: Vulnerability data fetched in parallel
-- **Smart Caching**: Reduces API calls and parsing overhead
+- **Concurrent Processing**: Vulnerability data fetched in parallel from multiple sources
+- **Multi-tier Caching**: Intelligent caching for both vulnerability data and resolved dependencies
 - **Efficient Matching**: In-memory indexing for fast vulnerability lookups
 - **Streaming**: Large databases processed without excessive memory usage
 
+### Resolution Cache Performance
+
+The resolution cache provides dramatic performance improvements for requirements.txt files:
+
+- **First scan**: Standard resolution time using `uv` or `pip-tools`
+- **Subsequent scans**: Near-instantaneous when cache is fresh (>90% time savings)
+- **Cache invalidation**: Automatic when requirements content, resolver, or environment changes
+- **Content-aware**: Different cache entries for different Python versions and platforms
+
 ### Requirements.txt Resolution Performance
 
-PySentry leverages external resolvers for optimal performance:
+PySentry leverages external resolvers with intelligent caching:
 
 - **uv resolver**: 2-10x faster than pip-tools, handles large dependency trees efficiently
 - **pip-tools resolver**: Reliable fallback, slower but widely compatible
 - **Isolated execution**: Prevents project pollution while maintaining security
-
-### Benchmarks
-
-Typical performance on a project with 100+ dependencies:
-
-- **Cold cache**: 15-30 seconds
-- **Warm cache**: 2-5 seconds
-- **Memory usage**: ~50MB peak
+- **Resolution caching**: Eliminates repeated resolver calls for unchanged requirements
 
 ## Development
 
@@ -555,12 +636,43 @@ ls uv.lock poetry.lock pyproject.toml
 **Performance Issues**
 
 ```bash
-# Clear cache and retry
-rm -rf ~/.cache/pysentry
+# Clear all caches and retry
+rm -rf ~/.cache/pysentry      # Linux
+rm -rf ~/Library/Caches/pysentry  # macOS
+pysentry
+
+# Clear only resolution cache (if vulnerability cache is working)
+rm -rf ~/.cache/pysentry/dependency-resolution/      # Linux
+rm -rf ~/Library/Caches/pysentry/dependency-resolution/  # macOS
 pysentry
 
+# Clear resolution cache via CLI
+pysentry --clear-resolution-cache
+
 # Use verbose mode to identify bottlenecks
 pysentry --verbose
+
+# Disable caching to isolate issues
+pysentry --no-cache
+```
+
+**Resolution Cache Issues**
+
+```bash
+# Clear stale resolution cache after environment changes
+pysentry --clear-resolution-cache
+
+# Disable resolution cache if causing issues
+pysentry --no-resolution-cache
+
+# Extend cache TTL for stable environments
+pysentry --resolution-cache-ttl 168  # 1 week
+
+# Check cache usage with verbose output
+pysentry --verbose  # Shows cache hits/misses
+
+# Force fresh resolution (ignores cache)
+pysentry --clear-resolution-cache --no-resolution-cache
 ```
 
 ## Acknowledgments