lenspr 0.1.1

Code intelligence for AI coding agents. Your AI sees dependencies before making changes.

Alpha (0.1.x) — works on real projects, used daily by the author. Expect rough edges.

AI assistants edit your code one file at a time. They don't see dependencies. They grep, read, guess — and break things three files away.

LensPR builds a dependency graph of your codebase and gives your AI structural understanding before it changes anything.

Quick Start

Requires Python 3.11+, macOS or Linux. For TypeScript/JS projects, also Node.js 18+.

pip install 'lenspr[all]'
lenspr init .
lenspr setup .

Restart your IDE. Done. Your AI now has lens_* tools.

Add .lens/ to your .gitignore — the graph is local and rebuilt from source.

What It Does

"What depends on this function?"

One call returns source code, who calls it, what it calls, and related tests:

> lens_context("auth.login_handler")

source: 42 lines
callers: auth_routes.create_routes, test_auth.test_login_success
callees: db.get_user, crypto.verify_password, jwt.create_token
tests: test_login_success, test_login_wrong_password

Without LensPR your AI makes 5-7 grep/read calls and still misses things. With LensPR — one call, full picture.

"What breaks if I change this?"

Before any modification, the AI sees the blast radius:

> lens_check_impact("models.User")

severity: CRITICAL
direct_dependents: 15
indirect_dependents: 23
affected_modules: auth, payments, notifications
tests_covering: 3

The AI warns you, changes its approach, or asks for confirmation. No more blind edits.

"How healthy is this codebase?"

> lens_vibecheck()

score: 86/100 (B)
  test_coverage:    17/25 — 67% functions tested
  dead_code:        20/20 — 0% dead code
  circular_imports: 15/15 — 0 cycles
  architecture:     12/15 — 1 violation
  documentation:     8/10 — 81% documented
  graph_confidence: 14/15 — 94% edges resolved

Track whether the codebase is improving or degrading over time.

Cross-language visibility

LensPR connects frontend and backend into a single graph:

LoginModal.tsx → fetch("/api/auth/login")
                        ↓ CALLS_API
Backend:  @router.post("/login") → login_handler()
            → db.query(User)        [reads: users]
            → verify_password()
            → create_jwt_token()

Also tracks: database tables, Docker services, env vars, CI/CD workflows, SQL migrations.

Works With

Languages: Python (95%+ resolution via Jedi/Pyright) and TypeScript/JavaScript (85-95% via tree-sitter + TS Compiler API).

Infrastructure: .sql files, Dockerfiles, docker-compose.yml, GitHub Actions workflows, .env files — all parsed into the same graph.

Everything runs locally. Your code never leaves your machine.

Key Features

60+ tools organized in 12 groups — enable only what you need with lenspr tools.

Known Limitations

• Windows — not supported. macOS and Linux only.
• self.method() calls — static parser can't fully resolve instance method dispatch. Workaround: lens_trace (Python 3.12+) resolves these at runtime.
• Go, Rust, Java — not yet supported. Parser interface is ready for contributors.
• Dynamic code — getattr, eval, dynamic imports can't be tracked statically.

Contributing

Try it. If it breaks, tell me.

• Bug reports — even "this doesn't work" is helpful
• Language parsers — Go, Rust, Java (BaseParser interface is ready)
• Ideas — open an issue

License

MIT

Built because AI kept breaking my code.