{"id":51241028,"url":"https://github.com/celpha2svx/solvix","last_synced_at":"2026-06-29T00:03:55.472Z","repository":{"id":359256652,"uuid":"1245177177","full_name":"celpha2svx/solvix","owner":"celpha2svx","description":"Code intelligence CLI — deterministic codebase analysis from inventory to maintainer-grade insights","archived":false,"fork":false,"pushed_at":"2026-06-14T17:27:21.000Z","size":400,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-28T06:05:42.889Z","etag":null,"topics":["cli","code-analysis","code-intelligence","developer-tools","python","static-analysis"],"latest_commit_sha":null,"homepage":"https://celpha2svx.github.io/solvix/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/celpha2svx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-21T01:39:22.000Z","updated_at":"2026-06-14T17:27:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/celpha2svx/solvix","commit_stats":null,"previous_names":["celpha2svx/solvix"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/celpha2svx/solvix","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/celpha2svx%2Fsolvix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/celpha2svx%2Fsolvix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/celpha2svx%2Fsolvix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/celpha2svx%2Fsolvix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/celpha2svx","download_url":"https://codeload.github.com/celpha2svx/solvix/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/celpha2svx%2Fsolvix/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34907995,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","code-analysis","code-intelligence","developer-tools","python","static-analysis"],"created_at":"2026-06-29T00:03:52.729Z","updated_at":"2026-06-29T00:03:55.467Z","avatar_url":"https://github.com/celpha2svx.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Solvix\n\nSolvix is a command-line tool for understanding a codebase and deciding where attention is useful.\n\nIt 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.\n\nSolvix is built for developers and maintainers who want more than a list of warnings. It is meant to help answer:\n\n- What kind of project is this?\n- Which files are central to the way it works?\n- Which function should I inspect first?\n- Is this worth a benchmark, a source review, or no action?\n- Why did Solvix reach that conclusion?\n- Did this finding appear before, change, or disappear?\n\nSolvix works without an API key. The core analysis is deterministic. The optional AI overlay is post-processing only.\n\n## When To Use Solvix\n\nUse Solvix when you want to understand a project before changing it.\n\nGood moments to run it:\n\n- Before starting work in an unfamiliar repository.\n- Before opening a pull request that touches important code.\n- When a project feels slow, risky, or hard to reason about.\n- During a weekly or release-readiness review.\n- After a refactor, to see whether the same findings remain.\n- Before writing an issue or outreach note, to make sure the claim is bounded and traceable.\n\nSolvix is not a replacement for tests, benchmarks, profiling, or maintainer judgment. It helps you decide where those efforts should go.\n\n## What Solvix Produces\n\nA project analysis gives you:\n\n- **Project identity**: application, CLI, framework, database engine, schema tool, rendering library, system software, and related objectives.\n- **Repository inventory**: what was scanned, skipped, parsed, and treated as source or peripheral code.\n- **Dependency and structural signals**: central files, graph confidence, unresolved imports, and runtime/core weighting.\n- **Repo-aware hotspots**: functions ranked by cost, relevance, project type, and source context.\n- **Multi-lens views**: maintainability, performance, startup, API stability, reliability, cloud cost, and battery where relevant.\n- **Deterministic judgment**: sendable, needs benchmark, or no-send.\n- **Trace ledger**: stable finding IDs and evidence steps showing why a target was selected.\n- **Run history**: optional comparison against the previous saved run.\n\n## Quick Start\n\nCheck your install and parser health:\n\n```bash\nsolvix doctor\n```\n\nAnalyze one file:\n\n```bash\nsolvix analyze path/to/file.py\n```\n\nAnalyze a whole project:\n\n```bash\nsolvix analyze path/to/project --project\n```\n\nSave a JSON report:\n\n```bash\nsolvix analyze path/to/project --project --json --output report.json\n```\n\nTrack the same repository over time:\n\n```bash\nsolvix analyze path/to/project --project --history\nsolvix analyze path/to/project --project --history\n```\n\nThe first history run creates a baseline. The next run marks findings as new, repeated, changed, or resolved.\n\n## Reading The Terminal Output\n\nProject mode starts with a **Solvix Maintainer Brief**.\n\nRead this first. It tells you:\n\n- the project identity Solvix inferred\n- the default lens selected for the repo\n- the current judgment status\n- the primary target, if one is ready\n- the confidence level\n- the trace ID\n- the history status\n- the next verification step\n\nExample history line:\n\n```text\nHistory        : compared with previous run; new=0, repeated=5, changed=0, resolved=0\n```\n\nWhat it means:\n\n- `new`: Solvix did not see this finding in the previous saved run.\n- `repeated`: the same finding is still present.\n- `changed`: the finding is still present but its status changed.\n- `resolved`: a previous finding is absent from the current run.\n\n## Judgment Status\n\nSolvix does not treat every finding as something to send or fix.\n\nIt uses three practical statuses:\n\n### `sendable`\n\nThere is a bounded action packet. The target is specific enough to inspect, benchmark, or discuss.\n\nThis does not mean \"open an issue immediately.\" It means the finding is strong enough to review seriously.\n\n### `needs_benchmark`\n\nThere is a plausible target, but the safest next step is measurement or source review.\n\nUse this when a claim might be real but needs proof before anyone should act on it.\n\n### `no_send`\n\nSolvix found signals, but they are too weak, intentional, low-impact, already benchmarked healthy, or not in the right code path.\n\nNo-send is important. It protects maintainer attention and helps prevent noisy reports.\n\n## Trace Ledger\n\nEvery project report includes a trace ledger.\n\nThe trace ledger gives findings stable IDs such as:\n\n```text\nsvx-52422549735e\n```\n\nUse the trace ID when you want to know:\n\n- why Solvix selected a target\n- which stage produced the evidence\n- whether the same finding appears in a later run\n- whether the finding changed or was resolved\n\nTrace steps connect the final judgment back to inventory, identity, graph confidence, lens selection, patterns, and verification guidance.\n\n## Run History\n\nRun history is opt-in.\n\n```bash\nsolvix analyze . --project --history\n```\n\nBy default, Solvix stores history under:\n\n```text\n.solvix/history/\n```\n\nYou can choose another location:\n\n```bash\nsolvix analyze . --project --history --history-dir .cache/solvix-history\n```\n\nUse history when you want Solvix to live with a project over time:\n\n- first run: create a baseline\n- later run: compare against the previous trace ledger\n- review repeated findings\n- confirm resolved findings\n- decide whether new findings need tests or benchmarks\n\n## Common Commands\n\n```bash\nsolvix --help\nsolvix doctor\nsolvix bootstrap-parsers --all\nsolvix analyze path/to/file.py\nsolvix analyze path/to/file.py --function my_function\nsolvix analyze path/to/project --project\nsolvix analyze path/to/project --project --history\nsolvix analyze path/to/project --project --json --output report.json\nsolvix analyze path/to/project --project --ai-mode assist\nsolvix --version\n```\n\n## Install\n\n### Python\n\n```bash\npip install solvix\n```\n\nFor local development:\n\n```bash\npip install -e .\n```\n\n### Windows\n\n```powershell\nwinget install Solvix.Solvix\n```\n\n### macOS\n\n```bash\nbrew tap celpha2svx/solvix\nbrew install solvix\n```\n\n### npm\n\n```bash\nnpm install -g @celpha2svx/solvix\n```\n\n### Linux or Generic Unix\n\n```bash\ncurl -fsSL https://github.com/celpha2svx/solvix/releases/latest/download/install.sh | sh\n```\n\n## Parser Setup\n\nSolvix uses built-in and native parsers where available.\n\nFor offline or restricted environments, prepare parsers ahead of time:\n\n```bash\nsolvix bootstrap-parsers --all\n```\n\nCheck parser health:\n\n```bash\nsolvix doctor\n```\n\n## Optional AI Overlay\n\nSolvix does not require AI.\n\nThe 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.\n\n```bash\nexport OPENAI_API_KEY=\"sk-...\"\nsolvix analyze . --project --ai-mode assist\n```\n\nOn Windows PowerShell:\n\n```powershell\n$env:OPENAI_API_KEY=\"sk-...\"\nsolvix analyze . --project --ai-mode assist\n```\n\nIf the AI overlay fails, deterministic reporting still succeeds.\n\n## Practical Workflow\n\nFor a new repository:\n\n```bash\nsolvix doctor\nsolvix analyze . --project --history\n```\n\nThen read:\n\n1. Maintainer Brief\n2. Judgment status\n3. Primary target\n4. Trace ID\n5. Next verification step\n6. No-send decisions\n\nFor an existing repository you already track:\n\n```bash\nsolvix analyze . --project --history\n```\n\nThen check:\n\n1. new findings\n2. changed findings\n3. repeated findings\n4. resolved findings\n\nFor a report you want to share:\n\n```bash\nsolvix analyze . --project --history --json --output solvix-report.json\n```\n\n## What Solvix Does Not Claim\n\nSolvix does not claim that every highlighted function is a bug.\n\nIt does not replace:\n\n- profiling\n- benchmarks\n- tests\n- code review\n- maintainer context\n\nIts job is to narrow attention, explain the evidence, and help you choose the next useful verification step.\n\n## Documentation\n\n- [Continuous Judgment Roadmap](docs/SOLVIX_CORE_CONTINUOUS_JUDGMENT_ROADMAP.md)\n- [Architecture](docs/ARCHITECTURE.md)\n- [Release Operations](docs/RELEASE_OPERATIONS.md)\n- [CLI UX and Release Readiness](docs/CLI_UX_AND_RELEASE_READINESS.md)\n- [Smoke Tests](docs/SMOKE_TESTS.md)\n- [Changelog](CHANGELOG.md)\n\n## Release Notes\n\nCurrent development is focused on Solvix Core as a continuous judgment system:\n\n- deterministic project understanding\n- judgment calibration\n- traceable findings\n- run history\n- clearer terminal output\n\nPackaging and distribution channels should be updated only after the tested CLI experience is stable.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcelpha2svx%2Fsolvix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcelpha2svx%2Fsolvix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcelpha2svx%2Fsolvix/lists"}