Skip to content

Docs/audit roadmap v0.5.1 v0.8.0 #15

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
M9nx merged 3 commits into from
Jul 22, 2026
Merged

Docs/audit roadmap v0.5.1 v0.8.0 #15

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d3cf388
chore: preserve audit tooling and dependency updates
M9nx Jul 22, 2026
f88235d
docs(audit): add reconciled codebase audit and release plan
M9nx Jul 22, 2026
9e612da
docs(site): publish roadmap and upcoming changes
M9nx Jul 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion docs/.vitepress/config.mts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,8 +49,9 @@ export default defineConfig({
items: [
{ text: 'Changelog', link: 'https://github.com/M9nx/CodexA/blob/main/CHANGELOG.md' },
{ text: 'Release Notes', link: 'https://github.com/M9nx/CodexA/blob/main/RELEASE_NOTES.md' },
{ text: 'Upgrade Guide', link: '/guide/upgrade' },
{ text: 'Roadmap', link: '/guide/roadmap' },
{ text: 'Upcoming Changes', link: '/guide/upcoming-changes' },
{ text: 'Upgrade Guide', link: '/guide/upgrade' },
],
},
{
Expand Down Expand Up @@ -93,6 +94,7 @@ export default defineConfig({
items: [
{ text: 'Contributing', link: '/guide/contributing' },
{ text: 'Roadmap', link: '/guide/roadmap' },
{ text: 'Upcoming Changes', link: '/guide/upcoming-changes' },
{ text: 'Upgrade Guide', link: '/guide/upgrade' },
],
},
Expand Down
143 changes: 143 additions & 0 deletions docs/audit/01-environment-baseline.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,143 @@
# 01 — Environment Baseline (Corrected v2)

**Audit Date:** 2026-07-22
**Auditor:** Senior Software Architect / Code Quality Auditor

---

## Git State

| Check | Result |
|-------|--------|
| Branch | `main` |
| Commit | `555506632fa76662318dacfa07d6f6c068393758` |
| Working-tree status | **Dirty** — configuration modified and reports added. No application source files modified. |

### Exact Changed Repository Files

```text
M pyproject.toml
M vscode-extension/package-lock.json
```

Additionally, untracked files (`??`) exist, primarily consisting of:
- `uv.lock` exists locally but is untracked and not committed or enforced by CI.
- `docs/audit/` and `docs/audit/evidence/` (generated reports and documentation)
- Various build artifacts and log files (`mypy_report.txt`, `pytest_report.txt`, `radon_report.txt`, `codexa-core/target/`)

**Nature of changes:**
- `pyproject.toml`: Configuration change (added `mypy` to dev dependencies).
- `vscode-extension/package-lock.json`: Configuration/lockfile change (from running `npm audit fix`).
- `uv.lock`: Generated lockfile.
- All other additions: Generated output or reports.
- **Application code:** Untouched.

---

## Environment Validation Table

| Check | Result | Evidence | Impact |
|-------|--------|----------|--------|
| Python version | Python 3.13.9 (via `py`) | `py --version` | Supported (≥3.11 required) |
| `python` alias | **Not found** on PATH | `python --version` fails | Forces use of `py`; CI uses `python -m pip` which may fail |
| `python3` alias | **Not found** on PATH | `python3 --version` fails | Same impact as above |
| uv package manager | uv 0.10.9 | `uv --version` | Available as Python install fallback |
| Rust / Cargo | 1.94.0 (stable) | `cargo --version` | Supported |
| rustup | 1.28.2 | `rustup --version` | Present |
| rustc | 1.94.0 (4a4ef493e) | Via rustup | Supported |
| Node.js | v24.5.0 | `node.exe --version` | Supported |
| npm | 11.10.0 | `npm.cmd --version` | Supported |
| PowerShell execution policy | Restricted for `.ps1` scripts | `npm.ps1 cannot be loaded` | **Blocks** `npm` shorthand; must use `npm.cmd` |
| `mypy` | **Installed** | `uv run mypy` runs | Type checking baseline successfully captured |
| mingw gcc linker | Present but `lpython313` not found | `cargo test` link error | **Blocks** native Rust tests on Windows |
| `codexa_core` Rust wheel | Not built/installed | `use_rust()` returns False | Extension runs Python-only fallback; Rust path not tested |
| VS Code extension compiled | `tsc -p ./` succeeds | `npm run compile` exit 0 | Extension can be built |
| ESLint config | **Missing** `.eslintrc*` | `eslint` "couldn't find config" | Linting non-functional |
| `cargo audit` | Not run (cargo-audit not installed) | — | Supply-chain check skipped |
| `pip-audit` | **Run** on requirements.txt | Exit 0 | **0 known vulnerabilities** in core production deps |

---

## Repository Structure

```
CodexA/
├── .github/
│ ├── workflows/
│ │ ├── ci.yml # Python tests only; no mypy, no coverage gate
│ │ ├── build-wheels.yml # Rust wheel builds + PyPI publish on tag
│ │ └── deploy-docs.yml # VitePress docs deploy
│ ├── ISSUE_TEMPLATE/
│ ├── PULL_REQUEST_TEMPLATE.md
│ └── copilot-instructions.md
├── codexa-core/ # Rust native extension (PyO3)
│ ├── Cargo.toml # version 0.1.0 (diverged from Python 0.5.0)
│ ├── src/
│ │ ├── lib.rs # PyO3 module registration
│ │ ├── ann.rs # Flat vector store (replaces FAISS)
│ │ ├── hnsw.rs # HNSW ANN search
│ │ ├── bm25.rs # BM25 keyword index
│ │ ├── chunk.rs # Line-boundary code chunker
│ │ ├── ast_chunk.rs # Tree-sitter AST-aware chunker
│ │ ├── scan.rs # File scanner (blake3, parallel)
│ │ ├── hybrid.rs # Reciprocal Rank Fusion
│ │ ├── embed.rs # ONNX embedder (optional feature)
│ │ └── tantivy_search.rs # Tantivy full-text (optional feature)
├── semantic_code_intelligence/ # Python core (23,104 LoC production)
│ ├── cli/ # 40 command files + main.py + router.py
│ ├── analysis/ # Code quality, metrics, impact
│ ├── bridge/ # HTTP bridge server
│ ├── config/ # Settings, AppConfig
│ ├── context/ # AI context windows, memory
│ ├── daemon/ # File watcher
│ ├── docs/ # Doc generation
│ ├── embeddings/ # Model registry, enhanced embeddings
│ ├── evolution/ # Self-improving dev loop
│ ├── indexing/ # Parallel indexer, scanner, semantic chunker
│ ├── llm/ # LLM providers, RAG, reasoning, streaming
│ ├── lsp/ # LSP server stub
│ ├── mcp/ # MCP server (13 tools), Claude config
│ ├── parsing/ # tree-sitter parser
│ ├── plugins/ # Plugin system (22 hooks)
│ ├── scalability/ # Multi-repo, chunking strategies
│ ├── search/ # grep, hybrid, keyword, semantic
│ ├── services/ # IndexingService, SearchService
│ ├── sessions/ # Multi-agent session management
│ ├── storage/ # VectorStore, HashStore, SymbolRegistry
│ ├── tools/ # AI agent tool protocol (13 tools)
│ ├── tui/ # Textual TUI / fallback REPL
│ ├── utils/ # Logging, helpers
│ ├── web/ # Web UI + REST API
│ ├── workspace/ # Multi-repo workspace
│ ├── rust_backend.py # Rust integration bridge
│ └── tests/ # 46 test files
├── vscode-extension/
│ ├── src/extension.ts # Single 1,121-line TypeScript file
│ ├── package.json # v0.2.0 — ESLint 8 devDep, no eslintrc
│ └── tsconfig.json
├── docs/ # VitePress documentation
├── pyproject.toml # v0.5.0 — authoritative Python package config
├── requirements.txt # Duplicate of pyproject.toml deps (not pinned)
├── Dockerfile
├── codexa.spec # PyInstaller spec
└── package.json # Root: VitePress docs only
```

---

## Build Systems

| Component | Build System | Command |
|-----------|-------------|---------|
| Python package | setuptools + pyproject.toml | `uv pip install -e .` |
| Rust extension | maturin (wheel only) / cargo (dev) | `maturin develop` or `cargo build` |
| VS Code extension | tsc (TypeScript) | `npm run compile` |
| Documentation | VitePress (Node.js) | `npm run docs:dev` |
| Standalone binary | PyInstaller | `pyinstaller codexa.spec` |

---

## Environmental Limitations Affecting Audit

1. **Rust extension cannot link on Windows MinGW**: `cargo test` and `cargo build` (debug) fail because MinGW-GCC cannot locate `lpython313`. This is a **Windows-specific build environment defect**, not a code defect.
2. **`cargo-audit` not installed**: Supply-chain audit of Rust crates was performed via `Cargo.lock` inspection only.
100 changes: 100 additions & 0 deletions docs/audit/02-functional-inventory.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
# 02 — Functional Inventory (Corrected v2)

**Correction date:** 2026-07-22
**Changes from v1:**
- Replaced "verified working" with correct terminology: Source-confirmed, Unit-tested, Environment-blocked, etc.
- Explicitly distinguished Python-fallback, Rust-native, VS Code live-host, HTTP/MCP external-client, and mocked LLM-provider behaviour paths
- Removed claims about Rust-native behaviour being "tested" (wheel not installed)

---

## Validation Terminology

| Term | Meaning |
|------|---------|
| **Source-confirmed** | Code path exists and is structured correctly; not executed during this audit |
| **Unit-tested** | pytest unit tests cover the Python-fallback path |
| **Integration-tested** | Multiple components tested together (HTTP, DB, etc.) |
| **Manually smoke-tested** | Manually executed and observed to function |
| **End-to-end validated** | Full user flow from UI/CLI to storage tested |
| **Environment-blocked** | Could not be validated; environment constraint prevented execution |
| **Unverified** | No evidence of correct behaviour |

---

## Feature Inventory

| Feature | Component | Entry Point | Python-Fallback Status | Rust-Native Status | VS Code Status | HTTP/MCP Status | Test Coverage | Notes |
|---------|-----------|------------|----------------------|--------------------|--------------|----------------|--------------|-------|
| **Repository indexing** | `services/indexing_service.py` | `codexa index` | Unit-tested | Environment-blocked (wheel absent) | Source-confirmed | Unverified | 84% | — |
| **Incremental indexing** | `services/indexing_service.py` | `codexa index --add` / watch | Unit-tested | Environment-blocked | Source-confirmed | Unverified | 84% (shared) | — |
| **Force re-index** | `services/indexing_service.py` | `codexa index --force` | Unit-tested | N/A | Source-confirmed | Unverified | Tested | — |
| **Model-consistency guard** | `indexing/ + storage/` | Automatic on `index` | Unit-tested | N/A | N/A | N/A | Tested | — |
| **`.codexaignore` support** | `indexing/scanner.py` | Automatic | Unit-tested | Environment-blocked | N/A | N/A | 90% | — |
| **Ctrl+C partial-save** | `cli/commands/index_cmd.py` | Signal handler | Unit-tested | N/A | N/A | N/A | Tested | Windows SIGINT may not work in all terminals |
| **Parallel indexing** | `indexing/parallel.py` | Automatic | Unit-tested | Environment-blocked | N/A | N/A | 97% | — |
| **Semantic search (Python/FAISS)** | `services/search_service.py` | `codexa search` | Unit-tested | Environment-blocked | Source-confirmed | Unverified | 94% | Requires `codexa[ml]` |
| **Keyword / BM25 search** | `search/keyword_search.py` | `codexa search --mode keyword` | Unit-tested | Environment-blocked | Source-confirmed | Unverified | 75% | — |
| **Hybrid search (RRF)** | `search/hybrid_search.py` | `codexa search --mode hybrid` | Unit-tested | Environment-blocked | Source-confirmed | Unverified | 90% | — |
| **Regex / grep search** | `search/grep.py` | `codexa grep` | Unverified (21% coverage) | N/A | Source-confirmed | Unverified | **21%** | Low coverage; subprocess paths untested |
| **File-watch daemon** | `daemon/watcher.py` | `codexa watch` | Unit-tested (75%) | N/A | Source-confirmed | Unverified | 75% | Native watcher platform layer not tested |
| **Symbol extraction / parsing** | `parsing/parser.py` | Core (internal) | Unit-tested | Environment-blocked | N/A | N/A | 97% | — |
| **Symbol explanation** | `analysis/ + tools` | `codexa explain` | Unit-tested | N/A | Source-confirmed | Unverified | 84% | — |
| **Code context windows** | `context/` | `codexa context` | Unit-tested | N/A | Source-confirmed | Unverified | 95% | — |
| **Repository summary** | `analysis/` | `codexa summary` | Unit-tested | N/A | Source-confirmed | Unverified | Tested | — |
| **Dependency map** | `analysis/` | `codexa deps` | Unit-tested | N/A | Source-confirmed | Unverified | Tested | — |
| **Call graph** | `analysis/` | `codexa tool run get_call_graph` | Unit-tested | N/A | Source-confirmed | Unverified | Tested | — |
| **Code quality** | `analysis/` | `codexa quality` | Unit-tested | N/A | Source-confirmed | Unverified | Tested | — |
| **Code metrics** | `analysis/` | `codexa metrics` | Unit-tested | N/A | Source-confirmed | Unverified | Tested | — |
| **Hotspots** | `analysis/` | `codexa hotspots` | Unit-tested | N/A | Source-confirmed | Unverified | Tested | — |
| **Quality gate (CI)** | `analysis/` | `codexa gate` | Unit-tested | N/A | N/A | N/A | Tested | — |
| **Impact analysis** | `analysis/` | `codexa impact` | Unit-tested | N/A | Source-confirmed | Unverified | Tested | `analyze_impact` D-complexity |
| **AI Q&A (LLM)** | `llm/` | `codexa ask` | Mocked-LLM tested | N/A | Source-confirmed | Unverified | 48–59% | Real API calls unverified |
| **Code review (LLM)** | `llm/` | `codexa review` | Mocked-LLM tested | N/A | Source-confirmed | Unverified | Low | — |
| **Refactor suggestions** | `llm/` | `codexa refactor` | Mocked-LLM tested | N/A | Source-confirmed | Unverified | Low | — |
| **RAG pipeline** | `llm/rag.py` | Internal | Mocked-LLM tested | N/A | N/A | N/A | 77% | — |
| **Streaming responses** | `llm/streaming.py` | Internal | Mocked-LLM tested | N/A | N/A | N/A | **49%** | Under-tested |
| **Multi-turn chat** | `llm/conversation.py` | `codexa chat` | Unit-tested | N/A | Source-confirmed | Unverified | 95% | — |
| **Autonomous investigation** | `llm/investigation.py` | `codexa investigate` | Mocked-LLM tested | N/A | Source-confirmed | Unverified | **59%** | Experimental |
| **Cross-refactor** | `llm/cross_refactor.py` | `codexa cross-refactor` | Mocked-LLM tested | N/A | Source-confirmed | Unverified | **53%** | Experimental |
| **Self-improving evolution** | `evolution/` | `codexa evolve` | Unverified (67–83%) | N/A | N/A | N/A | 67–83% | Experimental |
| **PR summary** | `cli/commands/pr_summary_cmd.py` | `codexa pr-summary` | Source-confirmed | N/A | N/A | N/A | Low | — |
| **HTTP bridge server** | `bridge/` | `codexa serve` | Source-confirmed | N/A | N/A | Unverified | Not directly tested | — |
| **MCP server** | `mcp/__init__.py` | `codexa mcp` | Unverified (30%) | N/A | N/A | Unverified | **30%** | External-client behaviour unverified |
| **Claude Desktop auto-config** | `mcp/claude_config.py` | `codexa mcp --claude-config` | Unverified (**0%**) | N/A | N/A | N/A | **0%** | Entirely untested |
| **AI Agent Tool Protocol** | `tools/` | `codexa tool run/list/schema` | Unit-tested | N/A | Source-confirmed | Unverified | 84–99% | — |
| **Plugin system** | `plugins/` | `codexa plugin` | Unit-tested | N/A | N/A | N/A | 97% | — |
| **Workspace (multi-repo)** | `workspace/` | `codexa workspace` | Unit-tested | N/A | N/A | N/A | 91% | — |
| **TUI (Textual)** | `tui/` | `codexa tui` | Unverified (21%) | N/A | N/A | N/A | **21%** | D-complexity fallback repl |
| **Web UI** | `web/` | `codexa web` | Unverified (16–20%) | N/A | N/A | Unverified | **16–20%** | Severely under-tested |
| **Visualization (Mermaid)** | `web/visualize.py` | `codexa viz` | Unit-tested | N/A | N/A | N/A | 98% | — |
| **LSP server** | `lsp/` | `codexa lsp` | Unverified (39%) | N/A | N/A | Unverified | **39%** | Likely incomplete |
| **Configuration** | `config/settings.py` | `codexa init` | Unit-tested | N/A | N/A | N/A | Tested | — |
| **Model management** | `embeddings/model_registry.py` | `codexa models` | Unit-tested | N/A | Source-confirmed | N/A | 94% | — |
| **Doctor / health check** | `cli/commands/doctor_cmd.py` | `codexa doctor` | Unit-tested | N/A | Source-confirmed | N/A | Tested | — |
| **Logging** | `utils/logging.py` | Internal | Unit-tested | N/A | N/A | N/A | 98% | — |
| **VS Code sidebar (4 panels)** | `vscode-extension/src/extension.ts` | Extension activation | Source-confirmed | N/A | **Unverified** | N/A | **No tests** | Live host not tested |
| **VS Code keybindings** | `extension.ts` | Ctrl+Shift+F5/E/Q | Source-confirmed | N/A | **Unverified** | N/A | No tests | — |
| **VS Code CodeLens** | `extension.ts` | Editor | **Not implemented** | N/A | N/A | N/A | — | README claims it; source does not implement it |
| **Rust vector store (flat)** | `codexa-core/src/ann.rs` | When wheel installed | Environment-blocked | Environment-blocked | N/A | N/A | Not testable | Wheel not built |
| **Rust HNSW** | `codexa-core/src/hnsw.rs` | When wheel installed | Environment-blocked | Environment-blocked | N/A | N/A | Not testable | Same |
| **Rust BM25** | `codexa-core/src/bm25.rs` | When wheel installed | Environment-blocked | Environment-blocked | N/A | N/A | Not testable | Same |
| **Rust AST chunker** | `codexa-core/src/ast_chunk.rs` | When wheel installed | Environment-blocked | Environment-blocked | N/A | N/A | Not testable | Same |
| **ONNX embedding** | `codexa-core/src/embed.rs` | Optional feature | Environment-blocked | Environment-blocked | N/A | N/A | Not testable | Optional compile feature |
| **Tantivy full-text** | `codexa-core/src/tantivy_search.rs` | Optional feature | Environment-blocked | Environment-blocked | N/A | N/A | Not testable | Optional compile feature |
| **Editor plugins (Zed, JetBrains, etc.)** | `editors/` | External | **Not implemented** | N/A | N/A | N/A | — | README lists them; no code exists |

---

## Features Requiring Immediate Attention

| Feature | Issue | Finding |
|---------|-------|---------|
| VS Code CodeLens | Claimed in README; not in source | F-19 |
| Editor plugins (Zed, JetBrains, etc.) | Listed in README; not in repository | F-20 |
| MCP Claude auto-config | 0% coverage, unverified | F-09 |
| LSP server | 39% coverage, likely incomplete | F-13 |
| Web server | 16% coverage, unverified | F-10 |
| grep/search | 21% coverage, unverified | F-12 |
| LLM streaming | 49% coverage, mocked LLM only | F-14 |
| Cross-refactor | 53% coverage, mocked LLM only | — |
Loading
Loading