Metadata-Version: 2.4
Name: codegraph-viz
Version: 0.10.1
Summary: Local code intelligence, Impact Radius V2, SQLite memory, evaluation gates, and controlled agent modes and isolated implementation sessions
Author: Deep Patel
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# codegraph-viz 0.10.1

Local code intelligence for Python projects: dependency visualization, Impact Radius V2, SQLite memory, observable runs, governance, evaluation gates, controlled agents, and approval-gated isolated implementation sessions.

## Install

```bash
python -m pip install codegraph-viz
```

## Main commands

```bash
codegraph scan .
codegraph doctor .
codegraph guide . --open
codegraph serve .
codegraph info .
codegraph export .
codegraph impact . codegraph/scanner.py --max-depth 4
codegraph memory . --search "relative import"
codegraph note add . "Preserve scanner compatibility" --file codegraph/scanner.py
codegraph context . "Explain import resolution" --mode explain
codegraph run start . --task "Fix import resolution" --agent codex
codegraph governance status .
codegraph eval . --suite evaluations/cumulative-six-mode-golden-suite.json --contexts .codegraph/contexts
codegraph agent prepare . --mode explain --task "Explain scanner"
codegraph implement policy-init .
codegraph implement list .
codegraph mcp
codegraph studio . --open
codegraph start . --task "Plan the next change"
```


## First-run experience

`codegraph scan .` now opens **Codegraph Studio** on a **Start Here** page. The page contains step-by-step cards with copyable commands for scanning, live serving, impact analysis, AI context, memory, tracing, controlled agents, diagnostics, and isolated implementation.

Every scan also writes a small local guide:

```text
.codegraph/codegraphcommand.md
```

Run the read-only health check at any time:

```bash
codegraph doctor .
```

On Windows, the included helper performs installation, scan, browser launch, and health check in one command:

```powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\INSTALL_AND_OPEN_WINDOWS.ps1 -ProjectPath "C:\Jobs"
```

## Phase 10: isolated implementation

Phase 10 can prepare and validate local file changes only inside a detached Git worktree. Every mutation, test, shell command, and cleanup operation requires an action-scoped approval. The implementation layer records a hash-chained audit and exports patch evidence without committing or writing to a remote.

```bash
# Create the standard Phase 10 policy.
codegraph implement policy-init .

# Use governance commands to request and approve create_worktree.
# Then prepare a detached worktree session.
codegraph implement prepare . \
  --task "Add explicit validation" \
  --file codegraph/scanner.py \
  --approval-id APPROVAL_ID

# Apply an approved file write.
codegraph implement write . SESSION_ID codegraph/scanner.py \
  --content-file scanner.new.py \
  --approval-id APPROVAL_ID

# Approved delete, rename, and general no-shell command operations are also available.
codegraph implement rename . SESSION_ID old.py new.py --approval-id APPROVAL_ID
codegraph implement delete . SESSION_ID obsolete.py --approval-id APPROVAL_ID
codegraph implement command . SESSION_ID --approval-id APPROVAL_ID --command "python tools/check.py"

# Execute an approved allowlisted test command with no shell.
codegraph implement test . SESSION_ID \
  --approval-id APPROVAL_ID \
  --command "python -m pytest -q"

# Produce review-only patch evidence and verify its checksums/audit chain.
codegraph implement evidence . SESSION_ID
codegraph implement verify . SESSION_ID
codegraph implement bundle . SESSION_ID -o phase10-evidence.zip

# Remove the worktree after an explicit cleanup approval.
codegraph implement cleanup . SESSION_ID --approval-id APPROVAL_ID --force
```

Phase 10 permanently denies direct commit, push, tag, pull-request, package publication, dependency installation, permission changes, and network-write actions. It also detects a commit created indirectly by a test process, restores the original detached HEAD, preserves the file diff, and marks the session as a policy violation.

## Cumulative Phase 1–10 features

- **Scanner reliability:** complete Python signatures, relative imports, exclusions, syntax-error retention, bundled offline graph runtime, security signals, and optional Git/source enrichment.
- **Impact Radius V2:** direct and indirect dependents, depth, shortest paths, cycles, truncation, cross-module spread, score, and severity.
- **Persistent memory:** local SQLite files, symbols, edges, durable memory, human notes, snapshots, context history, migration, retention, compaction, and exports.
- **Run tracing:** baselines, checkpoints, patches, commands, test evidence, summaries, and offline HTML timelines.
- **Governance:** policies, path scopes, sensitive-file blocks, approvals, assignments, handoffs, governed execution, and tamper-evident audit logs.
- **Studio:** Files, Changes, Impact, Memory, Runs, Govern, Evaluations, Agent Control, Implementation, and MCP in one offline HTML application.
- **MCP:** deterministic local read tools for graph, files, impact, memory, contexts, runs, governance, evaluations, controlled manifests, and Phase 10 session evidence.
- **Evaluation gates:** golden-case recall, precision, symbol coverage, ranking, token budgets, freshness, forbidden paths, explanations, and baselines.
- **Controlled agents:** `explain`, `onboard`, `debug`, `impact`, `review`, and `plan` remain read-only or plan-only.
- **Isolated implementation:** detached worktrees, explicit approvals, constrained command execution, patch evidence, verification, cleanup, and no automatic Git/remote writes.

## Local storage

```text
.codegraph/
├── graph.html
├── graph_data.json
├── studio.html
├── memory.sqlite3
├── codegraphcommand.md
├── context/
├── runs/
├── agent-runs/
├── evaluation/
├── governance.json
├── governance-audit.jsonl
└── implementation/
    └── sessions/
        └── impl-.../
            ├── session.json
            ├── plan.json
            ├── implementation-audit.jsonl
            ├── commands/
            └── evidence/
```

All project intelligence and implementation evidence remain local unless the user deliberately transfers an artifact elsewhere.

## Development

```bash
python -m pip install -e . pytest pytest-cov ruff build twine
python -m pytest
python -m pytest --cov=codegraph --cov-branch --cov-fail-under=95
python -m ruff format --check codegraph scripts tests
python -m ruff check codegraph scripts tests
python -m compileall -q codegraph scripts tests
python scripts/run_complete_demo.py
python scripts/run_phase10_demo.py
```

See [SECURITY.md](SECURITY.md), [PHASE_10_RESULTS.md](PHASE_10_RESULTS.md), and [RUN_WINDOWS.md](RUN_WINDOWS.md).
