feat(deps-audit): dependency vulnerability scan via OSV.dev API (closes #158)

README.md

@@ -2,12 +2,12 @@
 
 > **Before an AI writes a new class/id/function, CodeLens must be checked. This is not optional.**
 
-CodeLens is an AI-native code intelligence platform that gives AI agents **full visibility** into a codebase before they write any code. It prevents collision, overwrite of existing logic, security vulnerabilities, and dead code through 71 CLI commands, an MCP server with 69 tools (54 static + 15 dynamic), AST-based taint analysis, live CVE/OSV scanning, a plugin system with OWASP Top 10 + Compliance rule packs, a true graph data model (nodes + edges) for structural code queries, and token-efficient `--format compact` output for high-volume agent workflows (issue #17).
+CodeLens is an AI-native code intelligence platform that gives AI agents **full visibility** into a codebase before they write any code. It prevents collision, overwrite of existing logic, security vulnerabilities, and dead code through 76 CLI commands, an MCP server with 74 tools (56 static + 18 dynamic), AST-based taint analysis, live CVE/OSV scanning, a plugin system with OWASP Top 10 + Compliance rule packs, a true graph data model (nodes + edges) for structural code queries, and token-efficient `--format compact` output for high-volume agent workflows (issue #17).
 
 ## Features
 
-- **71 CLI Commands** — From basic scan/query to AST taint analysis, CVE scanning, plugin management, auto-fix, dashboards, CI/CD quality gates, and `graph-schema` for cheap graph-shape introspection
-- **MCP Server (69 Tools)** — Native AI agent integration via Model Context Protocol (JSON-RPC over stdio), 54 statically-defined tools + 15 dynamically discovered, every tool accepts a `format` parameter (`json`/`markdown`/`ai`/`sarif`/`compact`)
+- **76 CLI Commands** — From basic scan/query to AST taint analysis, CVE scanning, plugin management, auto-fix, dashboards, CI/CD quality gates, and `graph-schema` for cheap graph-shape introspection
+- **MCP Server (74 Tools)** — Native AI agent integration via Model Context Protocol (JSON-RPC over stdio), 56 statically-defined tools + 18 dynamically discovered, every tool accepts a `format` parameter (`json`/`markdown`/`ai`/`sarif`/`compact`)
 - **Token-Efficient Compact Output (v8.2, issue #17)** — `--format compact` produces single-char-key JSON with abbreviated types, omitted null fields, and relative paths — ~50% smaller than `json` on real trace output. Combined with `--limit`/`--offset` pagination, 5 structural queries now cost <5k tokens (down from 30-80k)
 - **AST Taint Engine** — Tree-sitter based taint analysis with return-value propagation, scope hierarchy, and branch condition refinement
 - **Live CVE/OSV Scanning** — Real-time vulnerability data from OSV.dev API with SQLite cache, 9 ecosystems (PyPI, npm, crates.io, Go, Maven, NuGet, RubyGems, Pub, Hex)
@@ -122,6 +122,7 @@ python3 scripts/codelens.py query "myFunction" --lite
 |---------|-------------|
 | `secrets [workspace] [--severity ...]` | Detect hardcoded API keys, passwords, tokens |
 | `vuln-scan [workspace] [--severity ...] [--offline] [--osv-ttl N] [--refresh] [--max-age Nh]` | Scan dependencies for known CVEs (OSV.dev + native audit). `--refresh` bypasses the OSV cache and forces fresh API calls; `--max-age Nh` treats cache entries older than N hours as stale for this run only (issue #30). Output includes a `cache_info` block (`last_refresh`, `age_hours`, `ttl_hours`, `is_stale`, `stale_packages`) so agents can decide whether to trust the cached CVE data. |
+| `deps-audit [workspace] [--severity ...] [--ecosystem PyPI\|npm\|crates.io] [--offline]` | Pure-Python dependency audit via OSV.dev batch API. Auto-detects `requirements.txt` / `pyproject.toml` / `Pipfile` (PyPI), `package.json` + lock files (npm), `Cargo.toml` + `Cargo.lock` (crates.io). Stores findings as `dependency_vuln` graph nodes linked via `HAS_VULN` edges (issue #158). |
 | `taint [workspace]` | Run AST-based taint analysis for vulnerability detection |
 | `dataflow [workspace] [--source] [--sink]` | Data flow taint analysis with cross-file call graph |
 | `env-check [workspace] [--var NAME]` | Audit environment variables |
@@ -225,8 +226,8 @@ codelens/
 │   ├── changelog.md               # Older changelog (per-version highlights)
 │   └── agent-integration.md       # AI agent integration guide
 ├── scripts/
-│   ├── codelens.py                # CLI entry point (71 commands registered)
-│   ├── mcp_server.py              # MCP JSON-RPC server (69 tools)
+│   ├── codelens.py                # CLI entry point (76 commands registered)
+│   ├── mcp_server.py              # MCP JSON-RPC server (74 tools)
 │   ├── registry.py                # Registry read/write/build
 │   ├── persistent_registry.py     # SQLite persistent storage (WAL mode)
 │   ├── base_parser.py             # Base tree-sitter parser

SKILL-QUICK.md

@@ -116,7 +116,7 @@ $CLI list --limit 5 --offset 10 --format compact            # → paginated + co
 | "Cross-file taint" | `dataflow` | `taint` (taint is single-file, AST-deep) |
 | "Auto-fix issues" | `fix` | `check` (check just gates, doesn't fix) |
 
-## All 71 Commands
+## All 76 Commands
 
 ### Setup & Lifecycle (8+)
 `init` · `scan [--incremental] [--max-files N] [--full]` · `registry-validate` · `detect` · `watch [--debounce SECS] [--git-mode] [--interval SECS]` · `git-status` · `migrate` · `serve` · `lsp-status` (issue #33: `codelens --lsp-status` top-level flag is an alias of `codelens lsp-status` — both delegate to `hybrid_engine.get_lsp_status()` and return the identical payload)
@@ -130,8 +130,8 @@ $CLI list --limit 5 --offset 10 --format compact            # → paginated + co
 ### Architecture (10)
 `entrypoints` · `api-map` · `state-map` · `detect` · `handbook` · `diff [--git-aware]` · `dashboard` · `history` · `graph-schema` · `resolve-types`
 
-### Security (5)
-`secrets [--severity ...]` · `taint` (AST-based) · `dataflow [--source ...] [--sink ...]` (cross-file) · `vuln-scan [--offline] [--osv-ttl N] [--refresh] [--max-age Nh]` (OSV.dev + native audit; `--refresh` bypasses cache, `--max-age Nh` overrides per-run TTL, `cache_info` in output signals staleness — issue #30) · `env-check [--var NAME]`
+### Security (6)
+`secrets [--severity ...]` · `taint` (AST-based) · `dataflow [--source ...] [--sink ...]` (cross-file) · `vuln-scan [--offline] [--osv-ttl N] [--refresh] [--max-age Nh]` (OSV.dev + native audit; `--refresh` bypasses cache, `--max-age Nh` overrides per-run TTL, `cache_info` in output signals staleness — issue #30) · `deps-audit [--severity ...] [--ecosystem PyPI|npm|crates.io] [--offline]` (pure-Python OSV.dev dependency audit, stores findings as `dependency_vuln` graph nodes — issue #158) · `env-check [--var NAME]`
 
 ### Quality (9)
 `smell [--categories ...] [--severity ...]` · `complexity [--name FN] [--threshold N] [--sort ...]` · `dead-code [--categories ...]` · `debug-leak [--category ...]` · `circular [--domain ...]` · `missing-refs` · `side-effect [--name FN]` · `perf-hint [--severity ...] [--category ...]` · `fix [--apply]`
@@ -148,19 +148,19 @@ $CLI list --limit 5 --offset 10 --format compact            # → paginated + co
 ### Tooling (1)
 `plugin <install|list|search|update|info|validate>`
 
-**Total: 71 commands** (auto-registered via `commands/__init__.py`; rerun `python3 scripts/sync_command_count.py --apply` after adding/removing a command)
+**Total: 76 commands** (auto-registered via `commands/__init__.py`; rerun `python3 scripts/sync_command_count.py --apply` after adding/removing a command)
 
-## MCP Server (69 Tools)
+## MCP Server (74 Tools)
 
 Start the MCP server for AI agent integration:
 
 ```bash
 python3 scripts/codelens.py serve
 ```
 
-Exposes 69 tools as `codelens_<command>` (e.g., `codelens_query`, `codelens_taint`, `codelens_graph_schema`, `codelens_architecture`, `codelens_resolve_types`, `codelens_git_status`):
+Exposes 74 tools as `codelens_<command>` (e.g., `codelens_query`, `codelens_taint`, `codelens_graph_schema`, `codelens_architecture`, `codelens_resolve_types`, `codelens_git_status`):
 - 50 statically-defined tools (full JSON schemas in `mcp_server.py`)
-- 15 dynamically-discovered tools (auto-discovered from `COMMAND_REGISTRY`; long-running `watch` and `serve` are excluded)
+- 18 dynamically-discovered tools (auto-discovered from `COMMAND_REGISTRY`; long-running `watch` and `serve` are excluded)
 - Every tool accepts a `format` parameter (`json`/`markdown`/`ai`/`sarif`/`compact`). Use `format: "compact"` for token-efficient responses (~50% smaller than `json`).
 - `watch` and `serve` itself are excluded (long-running)
 

SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: codelens
 description: >
-  CodeLens — AI-Native Code Intelligence. 71 commands for AI-powered code analysis,
+  CodeLens — AI-Native Code Intelligence. 76 commands for AI-powered code analysis,
   security auditing, quality scoring, AST-based taint analysis, live CVE scanning,
   and pre-write safety checks. Supports 28+ languages with tree-sitter + regex
-  fallback parsing. MCP server exposes 69 tools for AI agent integration.
+  fallback parsing. MCP server exposes 74 tools for AI agent integration.
   For quick command reference with validated output schemas, see SKILL-QUICK.md.
   For version history, see CHANGELOG.md.
 ---

pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "codelens"
 version = "8.2.0"
-description = "Live Codebase Reference Intelligence — 71 commands for AI-powered code analysis, security auditing, and quality scoring"
+description = "Live Codebase Reference Intelligence — 76 commands for AI-powered code analysis, security auditing, and quality scoring"
 readme = "README.md"
 license = {text = "MIT"}
 requires-python = ">=3.8"

scripts/codelens.py

@@ -395,7 +395,7 @@ def _auto_setup(workspace: str) -> Dict[str, Any]:
     "secrets", "a11y", "css-deep", "regex-audit", "vuln-scan",
     "side-effect", "missing-refs", "circular", "list", "env-check",
     "test-map", "ownership", "entrypoints", "api-map", "state-map",
-    "dataflow", "search", "symbols", "summary", "taint",
+    "dataflow", "search", "symbols", "summary", "taint", "deps-audit",
 }
 
 # Sort strategies per command for --top (sort by relevance before truncating)
@@ -406,6 +406,7 @@ def _auto_setup(workspace: str) -> Dict[str, Any]:
     "perf-hint": ("severity", True),          # sort by severity desc
     "secrets": ("severity", True),            # sort by severity desc
     "vuln-scan": ("severity", True),          # sort by severity desc
+    "deps-audit": ("severity", True),         # sort by severity desc (issue #158)
     "a11y": ("severity", True),               # sort by severity desc
     "css-deep": ("severity", True),           # sort by severity desc
     "regex-audit": ("severity", True),        # sort by severity desc

scripts/commands/deps_audit.py

@@ -0,0 +1,52 @@
+# @WHO:   scripts/commands/deps_audit.py
+# @WHAT:  deps-audit CLI command — dependency vulnerability scan via OSV.dev
+# @PART:  commands
+# @ENTRY: execute()
+"""Deps-audit command — Scan dependencies for known CVEs via OSV.dev API."""
+
+from dep_audit_engine import audit_dependencies
+from commands import register_command
+
+
+def add_args(parser):
+    parser.add_argument(
+        "workspace",
+        nargs="?",
+        default=None,
+        help="Path to workspace root (auto-detected if omitted)",
+    )
+    parser.add_argument(
+        "--severity",
+        choices=["critical", "high", "medium", "low"],
+        default=None,
+        help="Filter by severity (includes higher severities)",
+    )
+    parser.add_argument(
+        "--ecosystem",
+        choices=["PyPI", "npm", "crates.io"],
+        default=None,
+        help="Limit scan to one package ecosystem",
+    )
+    parser.add_argument(
+        "--offline",
+        action="store_true",
+        default=False,
+        help="Skip OSV API queries (report packages only, no findings)",
+    )
+
+
+def execute(args, workspace):
+    return audit_dependencies(
+        workspace,
+        severity=args.severity,
+        ecosystem=args.ecosystem,
+        offline=args.offline,
+    )
+
+
+register_command(
+    "deps-audit",
+    "Scan dependencies for known CVEs via OSV.dev (PyPI/npm/crates.io)",
+    add_args,
+    execute,
+)