Metadata-Version: 2.4
Name: codeknow
Version: 1.1.2
Summary: Turn any codebase into a queryable knowledge graph -- architecture health, drift detection, impact analysis, 25+ languages, zero-LLM default
Author: Alex Salsali
License-Expression: MIT
Project-URL: Homepage, https://github.com/asalsali/codeknow
Project-URL: Repository, https://github.com/asalsali/codeknow
Project-URL: Changelog, https://github.com/asalsali/codeknow/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/asalsali/codeknow/issues
Keywords: knowledge-graph,tree-sitter,code-analysis,ast,graph,simulation,architecture,mcp
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: networkx>=3.4
Requires-Dist: numpy>=1.21
Requires-Dist: rapidfuzz>=3.0
Requires-Dist: tree-sitter<0.26,>=0.23.0
Requires-Dist: tree-sitter-python<0.26,>=0.23
Requires-Dist: tree-sitter-javascript<0.26,>=0.23
Requires-Dist: tree-sitter-typescript<0.25,>=0.23
Requires-Dist: tree-sitter-go<0.26,>=0.23
Requires-Dist: tree-sitter-rust<0.25,>=0.23
Requires-Dist: tree-sitter-java<0.25,>=0.23
Requires-Dist: tree-sitter-groovy<0.3,>=0.1
Requires-Dist: tree-sitter-c<0.25,>=0.23
Requires-Dist: tree-sitter-cpp<0.25,>=0.23
Requires-Dist: tree-sitter-ruby<0.25,>=0.23
Requires-Dist: tree-sitter-c-sharp<0.25,>=0.23
Requires-Dist: tree-sitter-kotlin<2.0,>=1.0
Requires-Dist: tree-sitter-scala<0.27,>=0.23
Requires-Dist: tree-sitter-php<0.25,>=0.23
Requires-Dist: tree-sitter-swift<0.9,>=0.7
Requires-Dist: tree-sitter-lua<0.6,>=0.2
Requires-Dist: tree-sitter-zig<2.0,>=1.0
Requires-Dist: tree-sitter-powershell<0.28,>=0.26
Requires-Dist: tree-sitter-elixir<0.5,>=0.3
Requires-Dist: tree-sitter-objc<4.0,>=3.0
Requires-Dist: tree-sitter-julia<0.25,>=0.23
Requires-Dist: tree-sitter-verilog<2.0,>=1.0
Requires-Dist: tree-sitter-fortran<0.8,>=0.6
Requires-Dist: tree-sitter-bash<0.27,>=0.23
Requires-Dist: tree-sitter-json<0.26,>=0.23
Provides-Extra: mcp
Requires-Dist: mcp<3,>=1; extra == "mcp"
Requires-Dist: starlette<2,>=1.3.1; extra == "mcp"
Provides-Extra: neo4j
Requires-Dist: neo4j; extra == "neo4j"
Provides-Extra: falkordb
Requires-Dist: falkordb; extra == "falkordb"
Provides-Extra: pdf
Requires-Dist: pypdf>=6.12.0; extra == "pdf"
Requires-Dist: markdownify; extra == "pdf"
Provides-Extra: watch
Requires-Dist: watchdog; extra == "watch"
Provides-Extra: svg
Requires-Dist: matplotlib; extra == "svg"
Requires-Dist: numpy>=2.0; python_version >= "3.13" and extra == "svg"
Provides-Extra: leiden
Requires-Dist: graspologic; python_version < "3.13" and extra == "leiden"
Provides-Extra: office
Requires-Dist: python-docx; extra == "office"
Requires-Dist: openpyxl; extra == "office"
Provides-Extra: google
Requires-Dist: openpyxl; extra == "google"
Provides-Extra: postgres
Requires-Dist: psycopg[binary]; extra == "postgres"
Requires-Dist: tree-sitter-sql; extra == "postgres"
Provides-Extra: video
Requires-Dist: faster-whisper; python_version >= "3.11" and extra == "video"
Requires-Dist: yt-dlp>=2026.6.9; extra == "video"
Provides-Extra: openai
Requires-Dist: openai; extra == "openai"
Requires-Dist: tiktoken; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic; extra == "anthropic"
Provides-Extra: gemini
Requires-Dist: openai; extra == "gemini"
Requires-Dist: tiktoken; extra == "gemini"
Provides-Extra: ollama
Requires-Dist: openai; extra == "ollama"
Provides-Extra: bedrock
Requires-Dist: boto3; extra == "bedrock"
Provides-Extra: chinese
Requires-Dist: jieba; extra == "chinese"
Provides-Extra: sql
Requires-Dist: tree-sitter-sql; extra == "sql"
Provides-Extra: pascal
Requires-Dist: tree-sitter-pascal; extra == "pascal"
Provides-Extra: dm
Requires-Dist: tree-sitter-dm; extra == "dm"
Provides-Extra: terraform
Requires-Dist: tree-sitter-hcl; extra == "terraform"
Provides-Extra: ocaml
Requires-Dist: tree-sitter-ocaml; extra == "ocaml"
Provides-Extra: commonlisp
Requires-Dist: tree-sitter-commonlisp; extra == "commonlisp"
Provides-Extra: robot
Requires-Dist: robotframework>=4.0; extra == "robot"
Provides-Extra: all
Requires-Dist: mcp<3,>=1; extra == "all"
Requires-Dist: starlette<2,>=1.3.1; extra == "all"
Requires-Dist: neo4j; extra == "all"
Requires-Dist: falkordb; extra == "all"
Requires-Dist: pypdf>=6.12.0; extra == "all"
Requires-Dist: markdownify; extra == "all"
Requires-Dist: watchdog; extra == "all"
Requires-Dist: python-docx; extra == "all"
Requires-Dist: openpyxl; extra == "all"
Requires-Dist: openai; extra == "all"
Requires-Dist: tiktoken; extra == "all"
Requires-Dist: anthropic; extra == "all"
Requires-Dist: boto3; extra == "all"
Requires-Dist: tree-sitter-sql; extra == "all"
Requires-Dist: jieba; extra == "all"
Requires-Dist: tree-sitter-hcl; extra == "all"
Requires-Dist: tree-sitter-pascal; extra == "all"
Requires-Dist: tree-sitter-ocaml; extra == "all"
Requires-Dist: tree-sitter-commonlisp; extra == "all"
Requires-Dist: robotframework>=4.0; extra == "all"
Dynamic: license-file

# Codeknow

Turn any codebase into a queryable knowledge graph. Health scores, drift detection, impact analysis, onboarding guides -- all from your AST.

## Why Codeknow?

Most code intelligence tools need embeddings, vector stores, or LLM API keys before they do anything useful. Codeknow builds a real graph from your source code using tree-sitter AST parsing -- 25+ languages, zero configuration, no API keys required. The graph is a NetworkX DiGraph: nodes are symbols (functions, classes, modules), edges are relationships (imports, calls, inheritance). Every analysis command operates on this graph directly.

It works standalone or as a force multiplier for AI coding assistants (Claude Code, Cursor, Gemini CLI, Codex, and more).

## Quick Start

```bash
pip install codeknow

cd your-project/
codeknow .
```

That's it. Open `codegraph-out/graph.html` for the interactive visualization, or `codegraph-out/GRAPH_REPORT.md` for the architectural report.

## Core Commands

| Command | What it does |
|---------|-------------|
| `codeknow <path>` | Build knowledge graph from source code |
| `codeknow debt` | Composite health score (0-100) with letter grade |
| `codeknow drift snapshot` | Save current architecture as a named baseline |
| `codeknow drift compare` | Detect what changed since the last baseline |
| `codeknow onboard` | Generate a guided codebase tour from graph topology |
| `codeknow impact "<file>"` | Blast radius -- what breaks if you change this? |
| `codeknow test-impact` | Which tests to run for your changed files |
| `codeknow security` | Attack surface analysis: source-to-sink path tracing |
| `codeknow owners` | Git-blame overlay: knowledge silos, bus factor, orphaned code |
| `codeknow refactor-plan "<target>"` | Safe refactoring order with dependency-aware risk assessment |

### Example: `codeknow debt`

```
  ARCHITECTURAL DEBT SCORE
  ========================================

    72.4 / 100   [B]

  Graph: 1,247 nodes, 3,891 edges, 18 communities

  BREAKDOWN
  ----------------------------------------
  [========      ]  God Node Concentration (25%)
                    Top nodes: Router(47), Database(38), Config(31)
  [===========   ]  Cross-Community Coupling (25%)
                    412/3891 edges cross boundaries
  [=============]   Import Cycles (20%)
                    0 cycle(s) detected
  [=========     ]  Community Cohesion (20%)
                    Avg density: 34% across 18 communities
  [============  ]  Dead Code (10%)
                    89/1247 nodes unreferenced (7%)

  RECOMMENDATIONS
  ----------------------------------------
  1. Split Router (degree 47) -- extract route groups into sub-modules
  2. Reduce coupling between Community 3 <-> Community 7 (28 edges)
```

## All Commands

| Command | Description |
|---------|-------------|
| `codeknow <path>` | Build knowledge graph from source code |
| `codeknow update` | Incrementally rebuild only changed files |
| `codeknow debt` | Architectural debt score (0-100) with CI gating (`--threshold`) |
| `codeknow drift snapshot` | Save current graph as a named baseline |
| `codeknow drift compare` | Compare current graph against a baseline |
| `codeknow drift history` | List saved baselines |
| `codeknow changelog` | Git-aware architectural changelog (`--since 2w`, `--ref HEAD~10`) |
| `codeknow onboard` | Guided codebase tour from graph topology |
| `codeknow impact "<file>"` | Blast radius analysis with risk assessment |
| `codeknow test-impact` | Map changed files to affected tests (pipe to `xargs pytest`) |
| `codeknow security` | Attack surface: source-to-sink path tracing |
| `codeknow owners` | Ownership analysis: knowledge silos, bus factor, `--codeowners` generation |
| `codeknow refactor-plan "<target>"` | Dependency-aware refactoring plan with safe ordering |
| `codeknow tui` | Interactive terminal navigator (keyboard-driven, no dependencies) |
| `codeknow dashboard` | Live architecture dashboard at localhost:8787 |
| `codeknow affected "<node>"` | Reverse traversal: all nodes impacted by a change |
| `codeknow simulate remove "<node>"` | Simulate removing a node -- cascade analysis |
| `codeknow simulate merge "<A>" "<B>"` | Simulate merging two modules |
| `codeknow simulate refactor "<a>" "<b>" --into <name>` | Simulate extracting nodes into a new module |
| `codeknow discover` | Detect latent connections, bridges, capability clusters |
| `codeknow features` | Identify product features from code structure |
| `codeknow patterns` | Match against 10 software architecture patterns |
| `codeknow diagnose` | Diagnose architectural issues |
| `codeknow reflect` | Generate architectural reflection from saved Q&A |
| `codeknow explain "<node>"` | Explain a node and its connections |
| `codeknow path "<A>" "<B>"` | Shortest path between two concepts |
| `codeknow query "<question>"` | Natural language query (requires LLM) |
| `codeknow tree` | Interactive collapsible dependency tree (HTML) |
| `codeknow god-nodes` | List the most connected nodes |
| `codeknow prs` | PR dashboard: CI state, review status |
| `codeknow export html\|neo4j\|obsidian\|svg\|graphml\|callflow-html\|wiki` | Export to various formats |
| `codeknow global add <path>` | Add a repo to the cross-repo global graph |
| `codeknow benchmark` | Measure token reduction vs naive full-corpus approach |

All commands support `--json` for machine-readable output.

## Supported Languages (25+)

Python, JavaScript, TypeScript, Go, Rust, Java, C, C++, C#, Ruby, Kotlin, Scala, PHP, Swift, Lua, Zig, PowerShell, Elixir, Objective-C, Julia, Verilog, Fortran, Bash, Groovy, Apex, Dart, Pascal, OCaml, Common Lisp, Terraform (HCL), Robot Framework, DM (BYOND), Razor, Blade, SQL, JSON/config, Markdown

Language detection is automatic. Each language has a dedicated tree-sitter extractor.

## How It Works

```
Source Code
    |
    v
[tree-sitter AST parsing] -- per-language extractors for 25+ languages
    |
    v
[Symbol extraction] -- functions, classes, modules, imports, calls
    |
    v
[Cross-file resolution] -- resolve imports, inheritance, call chains
    |
    v
[NetworkX DiGraph] -- nodes = symbols, edges = relationships
    |
    v
[Analysis / Simulation / Visualization]
    |--- Debt scoring (health grade 0-100)
    |--- Drift detection (baseline snapshots)
    |--- Impact & test-impact analysis
    |--- Security (source-to-sink tracing)
    |--- Simulation engine (remove, merge, refactor)
    |--- Discovery engine (latent connections, features, patterns)
    |--- Interactive HTML + TUI + dashboard
    |--- Export (Neo4j, Obsidian, SVG, GraphML)
```

**Zero-LLM default mode**: The core pipeline (parse, build, analyze, simulate, discover, debt, drift, onboard, security, test-impact, owners, refactor-plan) works without any API key. LLM integration is optional for natural language queries, enriched reports, and community labeling.

## AI Agent Integration

```bash
codeknow install claude              # Claude Code
codeknow install cursor              # Cursor
codeknow install gemini              # Gemini CLI
codeknow install codex               # OpenAI Codex
codeknow install kilo                # Kilo Code
codeknow install vscode              # VS Code Copilot Chat
codeknow install antigravity         # Google Antigravity
codeknow install kiro                # Kiro IDE/CLI
```

An MCP server is also available:

```bash
pip install "codeknow[mcp]"
codeknow-mcp                        # exposes suggest_refactoring + impact_analysis tools
```

## CI Integration

Use `codeknow debt --threshold` as a CI quality gate:

```yaml
# .github/workflows/codeknow.yml
- name: Architecture health check
  run: |
    pip install codeknow
    codeknow . --code-only
    codeknow debt --threshold 60
```

Use `codeknow test-impact --changed` to run only affected tests:

```yaml
- name: Smart test selection
  run: |
    codeknow test-impact --changed | xargs pytest
```

## Optional Extras

```bash
pip install "codeknow[mcp]"          # MCP server for AI coding assistants
pip install "codeknow[openai]"       # OpenAI LLM integration
pip install "codeknow[anthropic]"    # Anthropic LLM integration
pip install "codeknow[ollama]"       # Ollama (local LLM) integration
pip install "codeknow[neo4j]"        # Neo4j graph database export
pip install "codeknow[falkordb]"     # FalkorDB graph database export
pip install "codeknow[pdf]"          # PDF document ingestion
pip install "codeknow[watch]"        # File watcher for live rebuilds
pip install "codeknow[svg]"          # Static SVG diagram export
pip install "codeknow[office]"       # Word/Excel document ingestion
pip install "codeknow[video]"        # Video transcription ingestion
pip install "codeknow[postgres]"     # PostgreSQL schema introspection
pip install "codeknow[all]"          # Everything
```

## Requirements

- Python 3.10+
- No API keys required for core functionality

## License

MIT License. See [LICENSE](LICENSE) for details.
