Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/celpha2svx/solvix

Code intelligence CLI — deterministic codebase analysis from inventory to maintainer-grade insights
https://github.com/celpha2svx/solvix

cli code-analysis code-intelligence developer-tools python static-analysis

Last synced: 9 days ago
JSON representation

Code intelligence CLI — deterministic codebase analysis from inventory to maintainer-grade insights

Awesome Lists containing this project

README 

          
# Solvix



Solvix is a command-line tool for understanding a codebase and deciding where attention is useful.



It scans a repository, identifies important files and functions, explains why they matter, and keeps a traceable record so the same findings can be followed across future runs.



Solvix is built for developers and maintainers who want more than a list of warnings. It is meant to help answer:



- What kind of project is this?

- Which files are central to the way it works?

- Which function should I inspect first?

- Is this worth a benchmark, a source review, or no action?

- Why did Solvix reach that conclusion?

- Did this finding appear before, change, or disappear?



Solvix works without an API key. The core analysis is deterministic. The optional AI overlay is post-processing only.



## When To Use Solvix



Use Solvix when you want to understand a project before changing it.



Good moments to run it:



- Before starting work in an unfamiliar repository.

- Before opening a pull request that touches important code.

- When a project feels slow, risky, or hard to reason about.

- During a weekly or release-readiness review.

- After a refactor, to see whether the same findings remain.

- Before writing an issue or outreach note, to make sure the claim is bounded and traceable.



Solvix is not a replacement for tests, benchmarks, profiling, or maintainer judgment. It helps you decide where those efforts should go.



## What Solvix Produces



A project analysis gives you:



- **Project identity**: application, CLI, framework, database engine, schema tool, rendering library, system software, and related objectives.

- **Repository inventory**: what was scanned, skipped, parsed, and treated as source or peripheral code.

- **Dependency and structural signals**: central files, graph confidence, unresolved imports, and runtime/core weighting.

- **Repo-aware hotspots**: functions ranked by cost, relevance, project type, and source context.

- **Multi-lens views**: maintainability, performance, startup, API stability, reliability, cloud cost, and battery where relevant.

- **Deterministic judgment**: sendable, needs benchmark, or no-send.

- **Trace ledger**: stable finding IDs and evidence steps showing why a target was selected.

- **Run history**: optional comparison against the previous saved run.



## Quick Start



Check your install and parser health:



```bash

solvix doctor

```



Analyze one file:



```bash

solvix analyze path/to/file.py

```



Analyze a whole project:



```bash

solvix analyze path/to/project --project

```



Save a JSON report:



```bash

solvix analyze path/to/project --project --json --output report.json

```



Track the same repository over time:



```bash

solvix analyze path/to/project --project --history

solvix analyze path/to/project --project --history

```



The first history run creates a baseline. The next run marks findings as new, repeated, changed, or resolved.



## Reading The Terminal Output



Project mode starts with a **Solvix Maintainer Brief**.



Read this first. It tells you:



- the project identity Solvix inferred

- the default lens selected for the repo

- the current judgment status

- the primary target, if one is ready

- the confidence level

- the trace ID

- the history status

- the next verification step



Example history line:



```text

History        : compared with previous run; new=0, repeated=5, changed=0, resolved=0

```



What it means:



- `new`: Solvix did not see this finding in the previous saved run.

- `repeated`: the same finding is still present.

- `changed`: the finding is still present but its status changed.

- `resolved`: a previous finding is absent from the current run.



## Judgment Status



Solvix does not treat every finding as something to send or fix.



It uses three practical statuses:



### `sendable`



There is a bounded action packet. The target is specific enough to inspect, benchmark, or discuss.



This does not mean "open an issue immediately." It means the finding is strong enough to review seriously.



### `needs_benchmark`



There is a plausible target, but the safest next step is measurement or source review.



Use this when a claim might be real but needs proof before anyone should act on it.



### `no_send`



Solvix found signals, but they are too weak, intentional, low-impact, already benchmarked healthy, or not in the right code path.



No-send is important. It protects maintainer attention and helps prevent noisy reports.



## Trace Ledger



Every project report includes a trace ledger.



The trace ledger gives findings stable IDs such as:



```text

svx-52422549735e

```



Use the trace ID when you want to know:



- why Solvix selected a target

- which stage produced the evidence

- whether the same finding appears in a later run

- whether the finding changed or was resolved



Trace steps connect the final judgment back to inventory, identity, graph confidence, lens selection, patterns, and verification guidance.



## Run History



Run history is opt-in.



```bash

solvix analyze . --project --history

```



By default, Solvix stores history under:



```text

.solvix/history/

```



You can choose another location:



```bash

solvix analyze . --project --history --history-dir .cache/solvix-history

```



Use history when you want Solvix to live with a project over time:



- first run: create a baseline

- later run: compare against the previous trace ledger

- review repeated findings

- confirm resolved findings

- decide whether new findings need tests or benchmarks



## Common Commands



```bash

solvix --help

solvix doctor

solvix bootstrap-parsers --all

solvix analyze path/to/file.py

solvix analyze path/to/file.py --function my_function

solvix analyze path/to/project --project

solvix analyze path/to/project --project --history

solvix analyze path/to/project --project --json --output report.json

solvix analyze path/to/project --project --ai-mode assist

solvix --version

```



## Install



### Python



```bash

pip install solvix

```



For local development:



```bash

pip install -e .

```



### Windows



```powershell

winget install Solvix.Solvix

```



### macOS



```bash

brew tap celpha2svx/solvix

brew install solvix

```



### npm



```bash

npm install -g @celpha2svx/solvix

```



### Linux or Generic Unix



```bash

curl -fsSL https://github.com/celpha2svx/solvix/releases/latest/download/install.sh | sh

```



## Parser Setup



Solvix uses built-in and native parsers where available.



For offline or restricted environments, prepare parsers ahead of time:



```bash

solvix bootstrap-parsers --all

```



Check parser health:



```bash

solvix doctor

```



## Optional AI Overlay



Solvix does not require AI.



The deterministic engine runs first and remains the source of truth. If enabled, the AI overlay receives compressed structured output and adds explanation after the core analysis.



```bash

export OPENAI_API_KEY="sk-..."

solvix analyze . --project --ai-mode assist

```



On Windows PowerShell:



```powershell

$env:OPENAI_API_KEY="sk-..."

solvix analyze . --project --ai-mode assist

```



If the AI overlay fails, deterministic reporting still succeeds.



## Practical Workflow



For a new repository:



```bash

solvix doctor

solvix analyze . --project --history

```



Then read:



1. Maintainer Brief

2. Judgment status

3. Primary target

4. Trace ID

5. Next verification step

6. No-send decisions



For an existing repository you already track:



```bash

solvix analyze . --project --history

```



Then check:



1. new findings

2. changed findings

3. repeated findings

4. resolved findings



For a report you want to share:



```bash

solvix analyze . --project --history --json --output solvix-report.json

```



## What Solvix Does Not Claim



Solvix does not claim that every highlighted function is a bug.



It does not replace:



- profiling

- benchmarks

- tests

- code review

- maintainer context



Its job is to narrow attention, explain the evidence, and help you choose the next useful verification step.



## Documentation



- [Continuous Judgment Roadmap](docs/SOLVIX_CORE_CONTINUOUS_JUDGMENT_ROADMAP.md)

- [Architecture](docs/ARCHITECTURE.md)

- [Release Operations](docs/RELEASE_OPERATIONS.md)

- [CLI UX and Release Readiness](docs/CLI_UX_AND_RELEASE_READINESS.md)

- [Smoke Tests](docs/SMOKE_TESTS.md)

- [Changelog](CHANGELOG.md)



## Release Notes



Current development is focused on Solvix Core as a continuous judgment system:



- deterministic project understanding

- judgment calibration

- traceable findings

- run history

- clearer terminal output



Packaging and distribution channels should be updated only after the tested CLI experience is stable.