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.
@@ -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
+ ```
@@ -0,0 +1,6 @@
1
+ """codebase-navigator: Git-aware ctags indexing, live watchers, and LanceDB semantic search."""
2
+
3
+ from __future__ import annotations
4
+
5
+ __version__ = "0.1.0"
6
+ __all__ = ["__version__"]