Skip to content
benzae1Public

About

No description, website, or topics provided.

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Qualgraph

CI Python License: MIT Release

Qualgraph is a local, graph-aware code quality analyzer for Python repositories. It builds a code graph, annotates it with quality signals, ranks risky code, and renders a Markdown report plus an offline web viewer.

The core idea is that structure, static analysis, coverage, git history, security findings, profiler data, and optional LLM findings all live on the same NetworkX graph. That makes cross-signal findings possible, such as complex code with weak tests, hidden git co-change coupling, and risky vulnerable imports.

Quickstart

Until the package is published to PyPI, install from the repository:

python -m pip install "git+https://github.com/benzae1/qualgraph.git"

For local development:

git clone https://github.com/benzae1/qualgraph.git
cd qualgraph
python -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"

On Windows PowerShell:

git clone https://github.com/benzae1/qualgraph.git
cd qualgraph
python -m venv .venv
.\.venv\Scripts\python -m pip install -e ".[dev]"

Run the full local workflow on the bundled tiny benchmark repository:

qualgraph analyze benchmarks/repos/tiny_repo --preset fast --coverage-mode skip --top-n 5

This writes:

  • .qualgraph/graph.json
  • .qualgraph/annotated.graph.json
  • .qualgraph/report.md
  • .qualgraph/export.json
  • .qualgraph/runs/<run_id>/run_summary.json

Open the local viewer:

qualgraph serve .qualgraph/annotated.graph.json --open

python -m qualgraph --help works too.

CLI

The one-command path is:

qualgraph analyze <repo> --preset standard

Useful focused commands:

qualgraph build <repo> --output .qualgraph/graph.json
qualgraph annotate <repo> --graph .qualgraph/graph.json --output .qualgraph/annotated.graph.json --annotators full
qualgraph report .qualgraph/annotated.graph.json --output .qualgraph/report.md
qualgraph export-json .qualgraph/annotated.graph.json --output .qualgraph/export.json
qualgraph serve .qualgraph/annotated.graph.json --open

Presets:

  • fast: radon, ruff, docstring, and cross-signal findings.
  • standard: fast plus git history and co-change.
  • full: standard plus vulture, coverage/test linkage, and security tools.

If .qualgraph/runs is not writable, pass a run-log directory:

qualgraph analyze . --artifacts-dir /tmp/qualgraph-runs

or set QUALGRAPH_ARTIFACTS_DIR.

LLM Workflows

Qualgraph does not require API keys. The subscription-friendly workflow exports focused task files for an agent to complete:

qualgraph llm export-tasks .qualgraph/annotated.graph.json --limit 20
qualgraph llm import-results .qualgraph/runs/<run_id> --graph .qualgraph/annotated.graph.json --output .qualgraph/final.graph.json
qualgraph report .qualgraph/final.graph.json --output .qualgraph/report.md

API-backed analysis is available for OpenAI, Anthropic, and local Ollama:

qualgraph llm analyze .qualgraph/annotated.graph.json --provider ollama --dry-run
qualgraph llm analyze .qualgraph/annotated.graph.json --provider openai --model gpt-4o-mini

User code stays local unless you explicitly choose an API provider.

Agent Skill

Qualgraph also ships with a reusable agent skill for Codex-style LLM workflows. If the agent is running inside this repository, the skill is already available from .agents/skills/qualgraph.

See Agent Skill for:

  • repo-local usage
  • global Codex skill installation
  • example prompts
  • expected outputs

Documentation

Development

python -m pip install -e ".[dev]"
python -m ruff check .
python -m pytest
python -m build
python -m twine check dist/*

Viewer browser checks require Chromium:

python -m playwright install chromium
python -m pytest tests/e2e -q

After code changes in this repository, run:

graphify update .

Status

Qualgraph is alpha software. The public interface is useful, but the graph schema and scoring model may still evolve before a stable 1.0 release.

About

No description, website, or topics provided.

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages