codebase-navigator 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- codebase_navigator-0.1.0/.envrc +1 -0
- codebase_navigator-0.1.0/.gitignore +47 -0
- codebase_navigator-0.1.0/PKG-INFO +114 -0
- codebase_navigator-0.1.0/README.md +99 -0
- codebase_navigator-0.1.0/flake.lock +133 -0
- codebase_navigator-0.1.0/flake.nix +120 -0
- codebase_navigator-0.1.0/pyproject.toml +50 -0
- codebase_navigator-0.1.0/skills/codebase-navigator/SKILL.md +123 -0
- codebase_navigator-0.1.0/src/codebase_navigator/__init__.py +6 -0
- codebase_navigator-0.1.0/src/codebase_navigator/ask.py +412 -0
- codebase_navigator-0.1.0/src/codebase_navigator/cli.py +230 -0
- codebase_navigator-0.1.0/src/codebase_navigator/config.py +102 -0
- codebase_navigator-0.1.0/src/codebase_navigator/extractor.py +281 -0
- codebase_navigator-0.1.0/src/codebase_navigator/index.py +279 -0
- codebase_navigator-0.1.0/src/codebase_navigator/ipc.py +221 -0
- codebase_navigator-0.1.0/src/codebase_navigator/tags.py +198 -0
- codebase_navigator-0.1.0/src/codebase_navigator/watcher.py +134 -0
- codebase_navigator-0.1.0/tests/test_cli.py +122 -0
- codebase_navigator-0.1.0/tests/test_extractor.py +66 -0
- codebase_navigator-0.1.0/tests/test_hybrid_search.py +36 -0
- codebase_navigator-0.1.0/tests/test_index.py +37 -0
- codebase_navigator-0.1.0/tests/test_ipc.py +124 -0
- codebase_navigator-0.1.0/tests/test_tags.py +39 -0
- codebase_navigator-0.1.0/tests/test_watcher.py +18 -0
- codebase_navigator-0.1.0/uv.lock +1768 -0
|
@@ -0,0 +1 @@
|
|
|
1
|
+
use flake
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
# Python
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*$py.class
|
|
5
|
+
*.so
|
|
6
|
+
.Python
|
|
7
|
+
build/
|
|
8
|
+
develop-eggs/
|
|
9
|
+
dist/
|
|
10
|
+
downloads/
|
|
11
|
+
eggs/
|
|
12
|
+
.eggs/
|
|
13
|
+
lib/
|
|
14
|
+
lib64/
|
|
15
|
+
parts/
|
|
16
|
+
sdist/
|
|
17
|
+
var/
|
|
18
|
+
wheels/
|
|
19
|
+
*.egg-info/
|
|
20
|
+
.installed.cfg
|
|
21
|
+
*.egg
|
|
22
|
+
|
|
23
|
+
# Virtual environments
|
|
24
|
+
.venv/
|
|
25
|
+
env/
|
|
26
|
+
venv/
|
|
27
|
+
ENV/
|
|
28
|
+
|
|
29
|
+
# Testing
|
|
30
|
+
.pytest_cache/
|
|
31
|
+
.coverage
|
|
32
|
+
htmlcov/
|
|
33
|
+
|
|
34
|
+
# Ruff
|
|
35
|
+
.ruff_cache/
|
|
36
|
+
|
|
37
|
+
# Direnv & Nix
|
|
38
|
+
.direnv/
|
|
39
|
+
result
|
|
40
|
+
result-*
|
|
41
|
+
|
|
42
|
+
# Index files & Ctags
|
|
43
|
+
.tags
|
|
44
|
+
tags
|
|
45
|
+
.devel-index/
|
|
46
|
+
.devel-tools/
|
|
47
|
+
.codebase-navigator/
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: codebase-navigator
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Fast Git-aware ctags indexing, live watchers, and LanceDB semantic search for developers
|
|
5
|
+
Author: Nigel Choi
|
|
6
|
+
License: MIT
|
|
7
|
+
Requires-Python: >=3.11
|
|
8
|
+
Requires-Dist: lancedb>=0.17.0
|
|
9
|
+
Requires-Dist: numpy>=1.24.0
|
|
10
|
+
Requires-Dist: pyarrow>=14.0.0
|
|
11
|
+
Requires-Dist: sentence-transformers>=3.0.0
|
|
12
|
+
Requires-Dist: torch
|
|
13
|
+
Requires-Dist: watchfiles>=0.24.0
|
|
14
|
+
Description-Content-Type: text/markdown
|
|
15
|
+
|
|
16
|
+
# codebase-navigator
|
|
17
|
+
|
|
18
|
+
Developer tools for ultra-fast codebase navigation, Git-aware ctags indexing, live watchers, and LanceDB semantic search.
|
|
19
|
+
|
|
20
|
+
## Quick Start
|
|
21
|
+
|
|
22
|
+
### Using nix
|
|
23
|
+
|
|
24
|
+
Run `cn` instantly without installing:
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
# Run directly from GitHub
|
|
28
|
+
nix run github:9gel/codebase-navigator -- sync
|
|
29
|
+
|
|
30
|
+
# Run help or any command
|
|
31
|
+
nix run github:9gel/codebase-navigator -- --help
|
|
32
|
+
nix run github:9gel/codebase-navigator -- search "authentication flow"
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
### Using uvx
|
|
36
|
+
|
|
37
|
+
You can run `cn` using `uvx` (the tool runner from [uv](https://docs.astral.sh/uv/)):
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
# Directly from the Git repository:
|
|
41
|
+
uvx --from git+https://github.com/9gel/codebase-navigator.git cn --help
|
|
42
|
+
|
|
43
|
+
# Once published to PyPI:
|
|
44
|
+
uvx codebase-navigator --help
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
> **Note:** `cn tags` requires `universal-ctags` and `git` to be installed on your system.
|
|
48
|
+
|
|
49
|
+
## Features
|
|
50
|
+
|
|
51
|
+
- 🏷️ **Git-Aware `.tags` Generation**: Uses `universal-ctags` to index genuine source code while completely ignoring huge data dumps, JSON caches, `.git`, `node_modules`, and build artifacts.
|
|
52
|
+
- 🧠 **LanceDB Semantic & Hybrid Search**: Vector search powered by `sentence-transformers/all-MiniLM-L6-v2` with hybrid phrase/title match boosting for markdown documentation, glossary terms, and code comments.
|
|
53
|
+
- ⚡ **Strict Offline Mode**: Runs 100% locally from disk cache with zero HuggingFace network requests or unauthenticated token warnings.
|
|
54
|
+
- 👀 **Live File Watcher**: Automatically re-indexes `.tags` and incrementally updates LanceDB embeddings on every save with sub-second debounce.
|
|
55
|
+
- 🔗 **Clickable GitHub Markdown Links**: Returns results formatted as `[file:Lstart-Lend](file:///abs_path#Lstart-Lend)`.
|
|
56
|
+
|
|
57
|
+
## Installation
|
|
58
|
+
|
|
59
|
+
### Nix Flakes
|
|
60
|
+
|
|
61
|
+
Add `codebase-navigator` to your `flake.nix`:
|
|
62
|
+
|
|
63
|
+
```nix
|
|
64
|
+
{
|
|
65
|
+
inputs = {
|
|
66
|
+
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
|
|
67
|
+
codebase-navigator = {
|
|
68
|
+
url = "github:9gel/codebase-navigator";
|
|
69
|
+
inputs.nixpkgs.follows = "nixpkgs";
|
|
70
|
+
};
|
|
71
|
+
};
|
|
72
|
+
|
|
73
|
+
outputs = { self, nixpkgs, codebase-navigator, ... }:
|
|
74
|
+
let
|
|
75
|
+
system = "x86_64-linux"; # or "aarch64-darwin", etc.
|
|
76
|
+
pkgs = nixpkgs.legacyPackages.''${system};
|
|
77
|
+
in
|
|
78
|
+
{
|
|
79
|
+
# Add to environment packages or devShells:
|
|
80
|
+
devShells.''${system}.default = pkgs.mkShell {
|
|
81
|
+
packages = [
|
|
82
|
+
codebase-navigator.packages.''${system}.default
|
|
83
|
+
];
|
|
84
|
+
};
|
|
85
|
+
};
|
|
86
|
+
}
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Or install it to your user profile:
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
nix profile install github:9gel/codebase-navigator
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
## CLI Commands
|
|
96
|
+
|
|
97
|
+
The unified `cn` command provides all indexing and search tools:
|
|
98
|
+
|
|
99
|
+
| Command | Purpose |
|
|
100
|
+
|---|---|
|
|
101
|
+
| `cn search <query> [folder]` | Semantic & hybrid search in markdown docs and code comments |
|
|
102
|
+
| `cn tags <symbol> [folder]` | Fast symbol definition lookup in `.tags` |
|
|
103
|
+
| `cn sync [folder] [--force]` | Synchronize `.tags` and LanceDB vector embeddings |
|
|
104
|
+
| `cn watch [folder]` | Live filesystem watcher for automatic re-indexing |
|
|
105
|
+
| `cn status [folder]` | Inspect index and `.tags` status |
|
|
106
|
+
|
|
107
|
+
## Development
|
|
108
|
+
|
|
109
|
+
Requires Nix and `direnv`:
|
|
110
|
+
|
|
111
|
+
```bash
|
|
112
|
+
direnv allow
|
|
113
|
+
uv run pytest
|
|
114
|
+
```
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
# codebase-navigator
|
|
2
|
+
|
|
3
|
+
Developer tools for ultra-fast codebase navigation, Git-aware ctags indexing, live watchers, and LanceDB semantic search.
|
|
4
|
+
|
|
5
|
+
## Quick Start
|
|
6
|
+
|
|
7
|
+
### Using nix
|
|
8
|
+
|
|
9
|
+
Run `cn` instantly without installing:
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
# Run directly from GitHub
|
|
13
|
+
nix run github:9gel/codebase-navigator -- sync
|
|
14
|
+
|
|
15
|
+
# Run help or any command
|
|
16
|
+
nix run github:9gel/codebase-navigator -- --help
|
|
17
|
+
nix run github:9gel/codebase-navigator -- search "authentication flow"
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
### Using uvx
|
|
21
|
+
|
|
22
|
+
You can run `cn` using `uvx` (the tool runner from [uv](https://docs.astral.sh/uv/)):
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
# Directly from the Git repository:
|
|
26
|
+
uvx --from git+https://github.com/9gel/codebase-navigator.git cn --help
|
|
27
|
+
|
|
28
|
+
# Once published to PyPI:
|
|
29
|
+
uvx codebase-navigator --help
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
> **Note:** `cn tags` requires `universal-ctags` and `git` to be installed on your system.
|
|
33
|
+
|
|
34
|
+
## Features
|
|
35
|
+
|
|
36
|
+
- 🏷️ **Git-Aware `.tags` Generation**: Uses `universal-ctags` to index genuine source code while completely ignoring huge data dumps, JSON caches, `.git`, `node_modules`, and build artifacts.
|
|
37
|
+
- 🧠 **LanceDB Semantic & Hybrid Search**: Vector search powered by `sentence-transformers/all-MiniLM-L6-v2` with hybrid phrase/title match boosting for markdown documentation, glossary terms, and code comments.
|
|
38
|
+
- ⚡ **Strict Offline Mode**: Runs 100% locally from disk cache with zero HuggingFace network requests or unauthenticated token warnings.
|
|
39
|
+
- 👀 **Live File Watcher**: Automatically re-indexes `.tags` and incrementally updates LanceDB embeddings on every save with sub-second debounce.
|
|
40
|
+
- 🔗 **Clickable GitHub Markdown Links**: Returns results formatted as `[file:Lstart-Lend](file:///abs_path#Lstart-Lend)`.
|
|
41
|
+
|
|
42
|
+
## Installation
|
|
43
|
+
|
|
44
|
+
### Nix Flakes
|
|
45
|
+
|
|
46
|
+
Add `codebase-navigator` to your `flake.nix`:
|
|
47
|
+
|
|
48
|
+
```nix
|
|
49
|
+
{
|
|
50
|
+
inputs = {
|
|
51
|
+
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
|
|
52
|
+
codebase-navigator = {
|
|
53
|
+
url = "github:9gel/codebase-navigator";
|
|
54
|
+
inputs.nixpkgs.follows = "nixpkgs";
|
|
55
|
+
};
|
|
56
|
+
};
|
|
57
|
+
|
|
58
|
+
outputs = { self, nixpkgs, codebase-navigator, ... }:
|
|
59
|
+
let
|
|
60
|
+
system = "x86_64-linux"; # or "aarch64-darwin", etc.
|
|
61
|
+
pkgs = nixpkgs.legacyPackages.''${system};
|
|
62
|
+
in
|
|
63
|
+
{
|
|
64
|
+
# Add to environment packages or devShells:
|
|
65
|
+
devShells.''${system}.default = pkgs.mkShell {
|
|
66
|
+
packages = [
|
|
67
|
+
codebase-navigator.packages.''${system}.default
|
|
68
|
+
];
|
|
69
|
+
};
|
|
70
|
+
};
|
|
71
|
+
}
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Or install it to your user profile:
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
nix profile install github:9gel/codebase-navigator
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
## CLI Commands
|
|
81
|
+
|
|
82
|
+
The unified `cn` command provides all indexing and search tools:
|
|
83
|
+
|
|
84
|
+
| Command | Purpose |
|
|
85
|
+
|---|---|
|
|
86
|
+
| `cn search <query> [folder]` | Semantic & hybrid search in markdown docs and code comments |
|
|
87
|
+
| `cn tags <symbol> [folder]` | Fast symbol definition lookup in `.tags` |
|
|
88
|
+
| `cn sync [folder] [--force]` | Synchronize `.tags` and LanceDB vector embeddings |
|
|
89
|
+
| `cn watch [folder]` | Live filesystem watcher for automatic re-indexing |
|
|
90
|
+
| `cn status [folder]` | Inspect index and `.tags` status |
|
|
91
|
+
|
|
92
|
+
## Development
|
|
93
|
+
|
|
94
|
+
Requires Nix and `direnv`:
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
direnv allow
|
|
98
|
+
uv run pytest
|
|
99
|
+
```
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
{
|
|
2
|
+
"nodes": {
|
|
3
|
+
"flake-utils": {
|
|
4
|
+
"inputs": {
|
|
5
|
+
"systems": "systems"
|
|
6
|
+
},
|
|
7
|
+
"locked": {
|
|
8
|
+
"lastModified": 1731533236,
|
|
9
|
+
"narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=",
|
|
10
|
+
"owner": "numtide",
|
|
11
|
+
"repo": "flake-utils",
|
|
12
|
+
"rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",
|
|
13
|
+
"type": "github"
|
|
14
|
+
},
|
|
15
|
+
"original": {
|
|
16
|
+
"owner": "numtide",
|
|
17
|
+
"repo": "flake-utils",
|
|
18
|
+
"type": "github"
|
|
19
|
+
}
|
|
20
|
+
},
|
|
21
|
+
"nixpkgs": {
|
|
22
|
+
"locked": {
|
|
23
|
+
"lastModified": 1787900134,
|
|
24
|
+
"narHash": "sha256-VYXO0XZlgj06dxJZRhrD3WoSsvq/c7+/Akyoa22pefw=",
|
|
25
|
+
"owner": "NixOS",
|
|
26
|
+
"repo": "nixpkgs",
|
|
27
|
+
"rev": "83199d0d373dd3ac2b9a1996b1d0263f76ab7a4c",
|
|
28
|
+
"type": "github"
|
|
29
|
+
},
|
|
30
|
+
"original": {
|
|
31
|
+
"owner": "NixOS",
|
|
32
|
+
"ref": "nixos-unstable",
|
|
33
|
+
"repo": "nixpkgs",
|
|
34
|
+
"type": "github"
|
|
35
|
+
}
|
|
36
|
+
},
|
|
37
|
+
"pyproject-build-systems": {
|
|
38
|
+
"inputs": {
|
|
39
|
+
"nixpkgs": [
|
|
40
|
+
"nixpkgs"
|
|
41
|
+
],
|
|
42
|
+
"pyproject-nix": [
|
|
43
|
+
"pyproject-nix"
|
|
44
|
+
],
|
|
45
|
+
"uv2nix": [
|
|
46
|
+
"uv2nix"
|
|
47
|
+
]
|
|
48
|
+
},
|
|
49
|
+
"locked": {
|
|
50
|
+
"lastModified": 1786936886,
|
|
51
|
+
"narHash": "sha256-8SFyOdmcG6Nsh/JzlH812lTI/v+ur06fpQhj/acNn8k=",
|
|
52
|
+
"owner": "pyproject-nix",
|
|
53
|
+
"repo": "build-system-pkgs",
|
|
54
|
+
"rev": "90ffdeee1a4929b231913df067448cd9803d3e07",
|
|
55
|
+
"type": "github"
|
|
56
|
+
},
|
|
57
|
+
"original": {
|
|
58
|
+
"owner": "pyproject-nix",
|
|
59
|
+
"repo": "build-system-pkgs",
|
|
60
|
+
"type": "github"
|
|
61
|
+
}
|
|
62
|
+
},
|
|
63
|
+
"pyproject-nix": {
|
|
64
|
+
"inputs": {
|
|
65
|
+
"nixpkgs": [
|
|
66
|
+
"nixpkgs"
|
|
67
|
+
]
|
|
68
|
+
},
|
|
69
|
+
"locked": {
|
|
70
|
+
"lastModified": 1786031528,
|
|
71
|
+
"narHash": "sha256-cROiHKO3UbIKqF5FG5NikvydzlfIj4EcR1Cty9qOVt4=",
|
|
72
|
+
"owner": "pyproject-nix",
|
|
73
|
+
"repo": "pyproject.nix",
|
|
74
|
+
"rev": "1b1485546d85f6f6c7aadb10c4923dbc09633263",
|
|
75
|
+
"type": "github"
|
|
76
|
+
},
|
|
77
|
+
"original": {
|
|
78
|
+
"owner": "pyproject-nix",
|
|
79
|
+
"repo": "pyproject.nix",
|
|
80
|
+
"type": "github"
|
|
81
|
+
}
|
|
82
|
+
},
|
|
83
|
+
"root": {
|
|
84
|
+
"inputs": {
|
|
85
|
+
"flake-utils": "flake-utils",
|
|
86
|
+
"nixpkgs": "nixpkgs",
|
|
87
|
+
"pyproject-build-systems": "pyproject-build-systems",
|
|
88
|
+
"pyproject-nix": "pyproject-nix",
|
|
89
|
+
"uv2nix": "uv2nix"
|
|
90
|
+
}
|
|
91
|
+
},
|
|
92
|
+
"systems": {
|
|
93
|
+
"locked": {
|
|
94
|
+
"lastModified": 1681028828,
|
|
95
|
+
"narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
|
|
96
|
+
"owner": "nix-systems",
|
|
97
|
+
"repo": "default",
|
|
98
|
+
"rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
|
|
99
|
+
"type": "github"
|
|
100
|
+
},
|
|
101
|
+
"original": {
|
|
102
|
+
"owner": "nix-systems",
|
|
103
|
+
"repo": "default",
|
|
104
|
+
"type": "github"
|
|
105
|
+
}
|
|
106
|
+
},
|
|
107
|
+
"uv2nix": {
|
|
108
|
+
"inputs": {
|
|
109
|
+
"nixpkgs": [
|
|
110
|
+
"nixpkgs"
|
|
111
|
+
],
|
|
112
|
+
"pyproject-nix": [
|
|
113
|
+
"pyproject-nix"
|
|
114
|
+
]
|
|
115
|
+
},
|
|
116
|
+
"locked": {
|
|
117
|
+
"lastModified": 1788001239,
|
|
118
|
+
"narHash": "sha256-AELmsXPI546MhbC/ZXC7WRUkCz7d4rqKTHUmliIgPpI=",
|
|
119
|
+
"owner": "pyproject-nix",
|
|
120
|
+
"repo": "uv2nix",
|
|
121
|
+
"rev": "7f9c6b613d2e749e54854b1d60ab6a2192db889e",
|
|
122
|
+
"type": "github"
|
|
123
|
+
},
|
|
124
|
+
"original": {
|
|
125
|
+
"owner": "pyproject-nix",
|
|
126
|
+
"repo": "uv2nix",
|
|
127
|
+
"type": "github"
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
},
|
|
131
|
+
"root": "root",
|
|
132
|
+
"version": 7
|
|
133
|
+
}
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
{
|
|
2
|
+
description = "codebase-navigator — Git-aware ctags indexing, live watchers, and LanceDB semantic search";
|
|
3
|
+
|
|
4
|
+
inputs = {
|
|
5
|
+
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
|
|
6
|
+
flake-utils.url = "github:numtide/flake-utils";
|
|
7
|
+
|
|
8
|
+
pyproject-nix = {
|
|
9
|
+
url = "github:pyproject-nix/pyproject.nix";
|
|
10
|
+
inputs.nixpkgs.follows = "nixpkgs";
|
|
11
|
+
};
|
|
12
|
+
uv2nix = {
|
|
13
|
+
url = "github:pyproject-nix/uv2nix";
|
|
14
|
+
inputs.nixpkgs.follows = "nixpkgs";
|
|
15
|
+
inputs.pyproject-nix.follows = "pyproject-nix";
|
|
16
|
+
};
|
|
17
|
+
pyproject-build-systems = {
|
|
18
|
+
url = "github:pyproject-nix/build-system-pkgs";
|
|
19
|
+
inputs.nixpkgs.follows = "nixpkgs";
|
|
20
|
+
inputs.pyproject-nix.follows = "pyproject-nix";
|
|
21
|
+
inputs.uv2nix.follows = "uv2nix";
|
|
22
|
+
};
|
|
23
|
+
};
|
|
24
|
+
|
|
25
|
+
outputs =
|
|
26
|
+
{
|
|
27
|
+
self,
|
|
28
|
+
nixpkgs,
|
|
29
|
+
flake-utils,
|
|
30
|
+
pyproject-nix,
|
|
31
|
+
uv2nix,
|
|
32
|
+
pyproject-build-systems,
|
|
33
|
+
}:
|
|
34
|
+
flake-utils.lib.eachDefaultSystem (system:
|
|
35
|
+
let
|
|
36
|
+
pkgs = import nixpkgs { inherit system; };
|
|
37
|
+
inherit (pkgs) lib;
|
|
38
|
+
python = pkgs.python312;
|
|
39
|
+
|
|
40
|
+
workspace = uv2nix.lib.workspace.loadWorkspace { workspaceRoot = ./.; };
|
|
41
|
+
lockedOverlay = workspace.mkPyprojectOverlay {
|
|
42
|
+
sourcePreference = "wheel";
|
|
43
|
+
};
|
|
44
|
+
|
|
45
|
+
# Disable auto-patchelf for torch wheel so its $ORIGIN RPATHs are preserved
|
|
46
|
+
pyprojectOverrides = final: prev: {
|
|
47
|
+
torch = prev.torch.overrideAttrs (_: { dontAutoPatchelf = true; });
|
|
48
|
+
};
|
|
49
|
+
|
|
50
|
+
pythonSet = (pkgs.callPackage pyproject-nix.build.packages {
|
|
51
|
+
inherit python;
|
|
52
|
+
}).overrideScope (lib.composeManyExtensions [
|
|
53
|
+
pyproject-build-systems.overlays.wheel
|
|
54
|
+
lockedOverlay
|
|
55
|
+
pyprojectOverrides
|
|
56
|
+
]);
|
|
57
|
+
|
|
58
|
+
runtimeEnv = pythonSet.mkVirtualEnv "codebase-navigator-env" workspace.deps.default;
|
|
59
|
+
runtimeLibs = "${lib.makeLibraryPath [ pkgs.stdenv.cc.cc.lib pkgs.zlib ]}";
|
|
60
|
+
|
|
61
|
+
# Runtime wrapper with universal-ctags, git, and offline HF environment
|
|
62
|
+
codebaseNavigator = pkgs.runCommand "codebase-navigator"
|
|
63
|
+
{ nativeBuildInputs = [ pkgs.makeWrapper ]; }
|
|
64
|
+
''
|
|
65
|
+
mkdir -p $out/bin
|
|
66
|
+
for b in cn; do
|
|
67
|
+
if [ -f "${runtimeEnv}/bin/$b" ]; then
|
|
68
|
+
makeWrapper "${runtimeEnv}/bin/$b" "$out/bin/$b" \
|
|
69
|
+
--prefix PATH : "${lib.makeBinPath [ pkgs.universal-ctags pkgs.git pkgs.coreutils ]}" \
|
|
70
|
+
--prefix LD_LIBRARY_PATH : "${runtimeLibs}" \
|
|
71
|
+
--set HF_HUB_OFFLINE "1" \
|
|
72
|
+
--set TRANSFORMERS_OFFLINE "1" \
|
|
73
|
+
--set HF_HUB_DISABLE_TELEMETRY "1" \
|
|
74
|
+
--set TRANSFORMERS_VERBOSITY "error" \
|
|
75
|
+
--run 'export TRITON_CACHE_DIR="''${XDG_CACHE_HOME:-$HOME/.cache}/triton"' \
|
|
76
|
+
--run 'export TORCH_HOME="''${XDG_CACHE_HOME:-$HOME/.cache}/torch"' \
|
|
77
|
+
--run 'export HF_HOME="''${XDG_CACHE_HOME:-$HOME/.cache}/huggingface"'
|
|
78
|
+
fi
|
|
79
|
+
done
|
|
80
|
+
'';
|
|
81
|
+
in
|
|
82
|
+
{
|
|
83
|
+
packages.default = codebaseNavigator;
|
|
84
|
+
packages.codebaseNavigator = codebaseNavigator;
|
|
85
|
+
packages.runtimeEnv = runtimeEnv;
|
|
86
|
+
|
|
87
|
+
apps.default = {
|
|
88
|
+
type = "app";
|
|
89
|
+
program = "${codebaseNavigator}/bin/cn";
|
|
90
|
+
};
|
|
91
|
+
apps.cn = { type = "app"; program = "${codebaseNavigator}/bin/cn"; };
|
|
92
|
+
|
|
93
|
+
# DevShell: uv manages development environment and .venv from uv.lock
|
|
94
|
+
devShells.default = pkgs.mkShell {
|
|
95
|
+
packages = [
|
|
96
|
+
python
|
|
97
|
+
pkgs.uv
|
|
98
|
+
pkgs.universal-ctags
|
|
99
|
+
pkgs.git
|
|
100
|
+
pkgs.ruff
|
|
101
|
+
];
|
|
102
|
+
env = {
|
|
103
|
+
UV_PYTHON = python.interpreter;
|
|
104
|
+
UV_PYTHON_DOWNLOADS = "never";
|
|
105
|
+
LD_LIBRARY_PATH = runtimeLibs;
|
|
106
|
+
HF_HUB_OFFLINE = "1";
|
|
107
|
+
TRANSFORMERS_OFFLINE = "1";
|
|
108
|
+
HF_HUB_DISABLE_TELEMETRY = "1";
|
|
109
|
+
TRANSFORMERS_VERBOSITY = "error";
|
|
110
|
+
};
|
|
111
|
+
shellHook = ''
|
|
112
|
+
unset PYTHONPATH
|
|
113
|
+
export TRITON_CACHE_DIR="''${XDG_CACHE_HOME:-$HOME/.cache}/triton"
|
|
114
|
+
export TORCH_HOME="''${XDG_CACHE_HOME:-$HOME/.cache}/torch"
|
|
115
|
+
export HF_HOME="''${XDG_CACHE_HOME:-$HOME/.cache}/huggingface"
|
|
116
|
+
echo "codebase-navigator devshell — try: uv run pytest | uv run cn --help"
|
|
117
|
+
'';
|
|
118
|
+
};
|
|
119
|
+
});
|
|
120
|
+
}
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "codebase-navigator"
|
|
3
|
+
version = "0.1.0"
|
|
4
|
+
description = "Fast Git-aware ctags indexing, live watchers, and LanceDB semantic search for developers"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
requires-python = ">=3.11"
|
|
7
|
+
license = { text = "MIT" }
|
|
8
|
+
authors = [{ name = "Nigel Choi" }]
|
|
9
|
+
|
|
10
|
+
dependencies = [
|
|
11
|
+
"lancedb>=0.17.0",
|
|
12
|
+
"sentence-transformers>=3.0.0",
|
|
13
|
+
"torch",
|
|
14
|
+
"watchfiles>=0.24.0",
|
|
15
|
+
"pyarrow>=14.0.0",
|
|
16
|
+
"numpy>=1.24.0",
|
|
17
|
+
]
|
|
18
|
+
|
|
19
|
+
[dependency-groups]
|
|
20
|
+
dev = [
|
|
21
|
+
"pytest>=8.0.0",
|
|
22
|
+
"pytest-cov>=4.0.0",
|
|
23
|
+
"ruff>=0.6.0",
|
|
24
|
+
]
|
|
25
|
+
|
|
26
|
+
[project.scripts]
|
|
27
|
+
cn = "codebase_navigator.cli:main"
|
|
28
|
+
|
|
29
|
+
[build-system]
|
|
30
|
+
requires = ["hatchling"]
|
|
31
|
+
build-backend = "hatchling.build"
|
|
32
|
+
|
|
33
|
+
[tool.hatch.build.targets.wheel]
|
|
34
|
+
packages = ["src/codebase_navigator"]
|
|
35
|
+
|
|
36
|
+
[tool.ruff]
|
|
37
|
+
line-length = 100
|
|
38
|
+
target-version = "py311"
|
|
39
|
+
|
|
40
|
+
[tool.pytest.ini_options]
|
|
41
|
+
testpaths = ["tests"]
|
|
42
|
+
|
|
43
|
+
[tool.uv.sources]
|
|
44
|
+
torch = { index = "pytorch-cpu" }
|
|
45
|
+
|
|
46
|
+
[[tool.uv.index]]
|
|
47
|
+
name = "pytorch-cpu"
|
|
48
|
+
url = "https://download.pytorch.org/whl/cpu"
|
|
49
|
+
explicit = true
|
|
50
|
+
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: codebase-navigator
|
|
3
|
+
description: Efficiently navigate codebases and project documentation using cn tools (cn search, cn tags, cn status, cn sync, cn watch). Use when locating concepts, architecture docs, symbol definitions, or maintaining live semantic indexes across development sessions.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Codebase Navigatory Guide
|
|
7
|
+
|
|
8
|
+
`codebase-navigator` (`cn`) provides high-speed code and documentation discovery for agents and developers. It complements `ripgrep` (`rg`) by providing semantic concept search and indexed ctags symbol navigation.
|
|
9
|
+
|
|
10
|
+
## Tool Suite Overview
|
|
11
|
+
|
|
12
|
+
| Command | Purpose | When to Use |
|
|
13
|
+
|---|---|---|
|
|
14
|
+
| `cn search` | Semantic vector search | Finding concepts, architectural docs, domain rules, and code docstrings |
|
|
15
|
+
| `cn tags` | Universal Ctags symbol lookup | Finding exact class, function, struct, or variable definitions |
|
|
16
|
+
| `cn status` | Index and daemon health | Checking indexed file counts and verifying if `ac watch` is active |
|
|
17
|
+
| `cn sync` | Full index synchronization | Forcing an immediate refresh of `.tags` and LanceDB vector embeddings |
|
|
18
|
+
| `cn watch` | Live background watcher & IPC daemon | Keeping indexes live and serving in-memory queries over Unix domain socket |
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## 1. Finding Concepts & Documentation (`cn search`)
|
|
23
|
+
|
|
24
|
+
Use `cn search` when you know *what* you want to achieve conceptually, but do not know the exact variable or file names:
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
# General conceptual search
|
|
28
|
+
cn search "content-addressed publisher bytes" .
|
|
29
|
+
|
|
30
|
+
# Filter for documentation only (.md, .rst, etc.)
|
|
31
|
+
cn search "data migration ledger" . --type md
|
|
32
|
+
|
|
33
|
+
# Filter for code comments and docstrings only
|
|
34
|
+
cn search "lot geometry transformation" . --type code
|
|
35
|
+
|
|
36
|
+
# Limit result count (default: 5)
|
|
37
|
+
cn search "authentication tokens" . --limit 3
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Results provide direct Markdown links with line ranges:
|
|
41
|
+
```markdown
|
|
42
|
+
### 1. [src/sitingdata_pipeline/sources/README.md:L1-L40](file:///.../sources/README.md#L1-L40) — Publisher source mechanics (Match: 88%)
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## 2. Locating Symbols & Definitions (`cn tags`)
|
|
48
|
+
|
|
49
|
+
Use `cn tags` for fast symbol lookups across large codebases without scanning file trees:
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
# Substring or regex symbol lookup
|
|
53
|
+
cn tags calculate_metrics .
|
|
54
|
+
|
|
55
|
+
# Exact symbol lookup
|
|
56
|
+
cn tags Defs . --excn
|
|
57
|
+
|
|
58
|
+
# Limit symbol results
|
|
59
|
+
cn tags parse_ . --limit 10
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Results output the symbol type, path, and definition snippet:
|
|
63
|
+
```text
|
|
64
|
+
1. `defs` (variable) -> [src/sitingdata_pipeline/definitions.py:L13](file:///.../definitions.py#L13)
|
|
65
|
+
`defs = dg.Definitions(`
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
|
|
70
|
+
## 3. Tool Selection: When to Use What
|
|
71
|
+
|
|
72
|
+
- **Use `cn search`** for domain logic questions, API specifications, workflow descriptions, and module purposes (e.g., *"where is the cache expiration logic?"*).
|
|
73
|
+
- **Use `cn tags`** when you know the identifier name (e.g., `BarrierReferenceStore`, `transform_records`) and need its declaration location.
|
|
74
|
+
- **Use `ripgrep` (`rg`)** for exact string occurrences, import statements, or regular expressions across code lines.
|
|
75
|
+
|
|
76
|
+
---
|
|
77
|
+
|
|
78
|
+
## 4. Index Lifecycle & Daemon Management
|
|
79
|
+
|
|
80
|
+
### Project Directory Layout
|
|
81
|
+
Indexes and runtime sockets are stored in the project-local `.codebase-navigator/` directory:
|
|
82
|
+
- `.codebase-navigator/lancedb` — Vector database
|
|
83
|
+
- `.codebase-navigator/files_meta.json` — Incremental mtime/size cache
|
|
84
|
+
- `.codebase-navigator/watch.sock` — Unix Domain Socket for fast IPC
|
|
85
|
+
|
|
86
|
+
### Checking Daemon & Index Status (`cn status`)
|
|
87
|
+
Always check the health and daemon status before starting work in a repository:
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
cn status .
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Example output:
|
|
94
|
+
```text
|
|
95
|
+
📊 Navigation Status for: /path/to/project
|
|
96
|
+
Available files: 924 source code files, 48 doc files
|
|
97
|
+
🏷️ Tags file: /path/to/project/.tags (1.77 MB)
|
|
98
|
+
🟢 cn watch daemon: ACTIVE (socket: /path/to/project/.codebase-navigator/watch.sock)
|
|
99
|
+
🧠 Vector index: /path/to/project/.codebase-navigator
|
|
100
|
+
Indexed files: 952, Total chunks: 7771
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
### Running the Live Daemon (`cn watch`)
|
|
104
|
+
A coordinating agent or background task can launch `cn watch` in the repository root:
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
cn watch .
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
- **Socket Acceleration**: When `cn watch` is running, `cn search` queries the in-memory index via `.codebase-navigator/watch.sock` in **< 30ms**, skipping Python ML library loading.
|
|
111
|
+
- **Concurrency Safety**: If multiple agents run `cn watch` under the same project directory, subsequent runs will detect the active socket and safely exit without conflicting.
|
|
112
|
+
- **Crash Recovery**: If `cn watch` was killed unexpectedly, stale socket files are automatically detected, unlinked, and recovered on subsequent commands.
|
|
113
|
+
|
|
114
|
+
### Manual Synchronization (`cn sync`)
|
|
115
|
+
If `cn watch` is not running and you pulled major changes or switched branches:
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
# Incremental sync (only changed files)
|
|
119
|
+
cn sync .
|
|
120
|
+
|
|
121
|
+
# Complete re-indexing from scratch
|
|
122
|
+
cn sync . --force
|
|
123
|
+
```
|