omphalos 1.1.1__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.
- omphalos-1.1.1/PKG-INFO +231 -0
- omphalos-1.1.1/README.md +197 -0
- omphalos-1.1.1/pyproject.toml +99 -0
- omphalos-1.1.1/pyproject.toml.orig +76 -0
- omphalos-1.1.1/src/omphalos/__init__.py +0 -0
- omphalos-1.1.1/src/omphalos/cache.py +58 -0
- omphalos-1.1.1/src/omphalos/cli.py +181 -0
- omphalos-1.1.1/src/omphalos/ignore.py +168 -0
- omphalos-1.1.1/src/omphalos/parser.py +519 -0
- omphalos-1.1.1/src/omphalos/render.py +69 -0
omphalos-1.1.1/PKG-INFO
ADDED
|
@@ -0,0 +1,231 @@
|
|
|
1
|
+
Metadata-Version: 2.3
|
|
2
|
+
Name: omphalos
|
|
3
|
+
Version: 1.1.1
|
|
4
|
+
Summary: Codebase symbol index for LLMs
|
|
5
|
+
Keywords: llm,indexer,tree-sitter,ast,codebase,symbols,agent
|
|
6
|
+
Author: snui1s
|
|
7
|
+
Author-email: snui1s <snailsqz@gmail.com>
|
|
8
|
+
License: MIT
|
|
9
|
+
Classifier: Development Status :: 4 - Beta
|
|
10
|
+
Classifier: Environment :: Console
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: Operating System :: OS Independent
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
18
|
+
Classifier: Topic :: Software Development :: Code Generators
|
|
19
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
20
|
+
Requires-Dist: typer>=0.12.0
|
|
21
|
+
Requires-Dist: pathspec>=1.1
|
|
22
|
+
Requires-Dist: tree-sitter>=0.24.0
|
|
23
|
+
Requires-Dist: tree-sitter-python>=0.25.0
|
|
24
|
+
Requires-Dist: tree-sitter-typescript>=0.23.0
|
|
25
|
+
Requires-Dist: tree-sitter-javascript>=0.25.0
|
|
26
|
+
Requires-Dist: tree-sitter-go>=0.25.0
|
|
27
|
+
Requires-Dist: tree-sitter-rust>=0.24.0
|
|
28
|
+
Requires-Python: >=3.10
|
|
29
|
+
Project-URL: Homepage, https://github.com/snui1s/Omphalos
|
|
30
|
+
Project-URL: Repository, https://github.com/snui1s/Omphalos
|
|
31
|
+
Project-URL: Issues, https://github.com/snui1s/Omphalos/issues
|
|
32
|
+
Project-URL: Changelog, https://github.com/snui1s/Omphalos/releases
|
|
33
|
+
Description-Content-Type: text/markdown
|
|
34
|
+
|
|
35
|
+
# Omphalos
|
|
36
|
+
|
|
37
|
+
[](https://github.com/RichardLitt/standard-readme)
|
|
38
|
+
[](https://github.com/snui1s/Omphalos/actions/workflows/ci.yml)
|
|
39
|
+
[](https://www.python.org/)
|
|
40
|
+
[](LICENSE)
|
|
41
|
+
|
|
42
|
+
> Codebase symbol indexer for LLMs.
|
|
43
|
+
|
|
44
|
+
Omphalos generates a compact, high-signal symbol map (`INDEX.md`) of your repository. It provides large language models and developers with an instant architectural overview and precise symbol locations—minimizing token usage and eliminating the need to read entire source files just to find declarations.
|
|
45
|
+
|
|
46
|
+
## Table of Contents
|
|
47
|
+
|
|
48
|
+
- [Omphalos](#omphalos)
|
|
49
|
+
- [Table of Contents](#table-of-contents)
|
|
50
|
+
- [Background](#background)
|
|
51
|
+
- [Install](#install)
|
|
52
|
+
- [Usage](#usage)
|
|
53
|
+
- [Quick Start](#quick-start)
|
|
54
|
+
- [CLI Reference](#cli-reference)
|
|
55
|
+
- [LLM / Agent Integration](#llm--agent-integration)
|
|
56
|
+
- [Development](#development)
|
|
57
|
+
- [Related Efforts](#related-efforts)
|
|
58
|
+
- [Maintainers](#maintainers)
|
|
59
|
+
- [Contributing](#contributing)
|
|
60
|
+
- [License](#license)
|
|
61
|
+
|
|
62
|
+
## Background
|
|
63
|
+
|
|
64
|
+
When providing a full codebase as context to Large Language Models (LLMs) or AI coding agents, feeding entire file contents quickly exhausts the model's context window, degrades reasoning performance, and incurs high token costs.
|
|
65
|
+
|
|
66
|
+
In practice, an agent rarely needs the implementation bodies of every file at once; it only needs an accurate structural index: what functions, classes, interfaces, and methods exist, where they are defined, and what their docstrings say.
|
|
67
|
+
|
|
68
|
+
Omphalos was created to solve this problem:
|
|
69
|
+
|
|
70
|
+
1. **Multi-language AST Parsing**: Uses Tree-sitter for deterministic parsing across Python, TypeScript/JavaScript, Go, and Rust.
|
|
71
|
+
2. **Precise Line Numbers (`@<line>`)**: Symbols indicate exact declaration line numbers so agents can inspect or slice specific ranges on demand.
|
|
72
|
+
3. **Internal Logic Hints**: Function-like symbols list their deduplicated call targets (`calls`) and raised exception types (`raises`), giving agents a control-flow preview without opening the file.
|
|
73
|
+
4. **Atomic Incremental Cache**: Tracks SHA-256 content hashes to re-parse only changed files, guaranteeing rapid re-indexes.
|
|
74
|
+
5. **CI/CD Integration**: Supports `--check` mode to ensure codebase indexes stay synchronized with changes.
|
|
75
|
+
|
|
76
|
+
## Install
|
|
77
|
+
|
|
78
|
+
### Using [uv](https://github.com/astral-sh/uv) (Recommended)
|
|
79
|
+
|
|
80
|
+
Run directly without installing:
|
|
81
|
+
|
|
82
|
+
```sh
|
|
83
|
+
$ uvx --from git+https://github.com/snui1s/Omphalos.git omph scan
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Or install as a standalone CLI tool:
|
|
87
|
+
|
|
88
|
+
```sh
|
|
89
|
+
$ uv tool install git+https://github.com/snui1s/Omphalos.git
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
### Using pip
|
|
93
|
+
|
|
94
|
+
```sh
|
|
95
|
+
$ pip install git+https://github.com/snui1s/Omphalos.git
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### Using npm / npx
|
|
99
|
+
|
|
100
|
+
Run directly via npx:
|
|
101
|
+
|
|
102
|
+
```sh
|
|
103
|
+
$ npx omphalos scan
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Or install globally:
|
|
107
|
+
|
|
108
|
+
```sh
|
|
109
|
+
$ npm install -g omphalos
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
### From Source
|
|
113
|
+
|
|
114
|
+
```sh
|
|
115
|
+
$ git clone https://github.com/snui1s/Omphalos.git
|
|
116
|
+
$ cd Omphalos
|
|
117
|
+
$ uv sync
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
## Usage
|
|
121
|
+
|
|
122
|
+
### Quick Start
|
|
123
|
+
|
|
124
|
+
1. **Initialize Ignore File** (creates default `.omphignore`):
|
|
125
|
+
|
|
126
|
+
```sh
|
|
127
|
+
$ omph init
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
2. **Generate the Symbol Index**:
|
|
131
|
+
|
|
132
|
+
```sh
|
|
133
|
+
$ omph scan
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
This generates `INDEX.md` in the root directory:
|
|
137
|
+
|
|
138
|
+
```markdown
|
|
139
|
+
# Codebase Symbol Index
|
|
140
|
+
|
|
141
|
+
## src/omphalos/cache.py
|
|
142
|
+
|
|
143
|
+
- `calculate_sha256()` @15: Calculate the SHA-256 checksum of raw file bytes for change detection. (calls: `hexdigest`, `hashlib.sha256`)
|
|
144
|
+
- `save_cache()` @38: Save symbol cache to .omphcache atomically. (calls: `tempfile.mkstemp`, `os.fdopen`, `json.dump`, `os.replace`, `os.unlink`)
|
|
145
|
+
|
|
146
|
+
## src/omphalos/cli.py
|
|
147
|
+
|
|
148
|
+
- `_version_callback()` @33: Callback for --version flag to print the version and exit immediately. (calls: `typer.echo`, `_package_version`; raises: `typer.Exit`)
|
|
149
|
+
|
|
150
|
+
## tests/fixtures/sample.ts
|
|
151
|
+
|
|
152
|
+
- export interface `UserProfile` @1
|
|
153
|
+
- export type `AuthToken` @6
|
|
154
|
+
- export function `verifyToken()` @8
|
|
155
|
+
- export class `SessionManager` @18
|
|
156
|
+
- `createSession()` @19
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
3. **Instruct AI Agents via `AGENTS.md`**:
|
|
160
|
+
|
|
161
|
+
Create or add to `AGENTS.md` (or `CLAUDE.md` / `.cursorrules`) at the root of your repository so AI agents read `INDEX.md` before exploring code:
|
|
162
|
+
|
|
163
|
+
```markdown
|
|
164
|
+
# Agent Guidelines
|
|
165
|
+
|
|
166
|
+
## Codebase Navigation & Exploration
|
|
167
|
+
|
|
168
|
+
Before searching, running grep, or opening entire source files across the codebase:
|
|
169
|
+
|
|
170
|
+
1. **Always read [`INDEX.md`](INDEX.md) first.** It provides an instant symbol map of the entire repository with exact line numbers.
|
|
171
|
+
2. Use the symbols, line locations (`@<line>`), and internal logic hints (`calls:`, `raises:`) in [`INDEX.md`](INDEX.md) to pinpoint definitions directly.
|
|
172
|
+
3. Inspect or slice-read only the specific line ranges or files needed for the task, rather than loading entire files into context.
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
### CLI Reference
|
|
176
|
+
|
|
177
|
+
```sh
|
|
178
|
+
$ omph scan [DIRECTORY] [OPTIONS]
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
The binary is installed as `omph`; the full name `omphalos` is also available as an alias.
|
|
182
|
+
|
|
183
|
+
| Option | Flag | Description |
|
|
184
|
+
| ---------------- | ------------------ | ------------------------------------------------------------------------- |
|
|
185
|
+
| `--output`, `-o` | `PATH` | Custom path for index output (default: `INDEX.md`). |
|
|
186
|
+
| `--format` | `markdown \| json` | Output format (default: `markdown`). |
|
|
187
|
+
| `--check` | flag | Verify index is up to date without writing. Exits with code `1` if stale. |
|
|
188
|
+
| `--git-only` | flag | Scan only files tracked by Git (`git ls-files`). |
|
|
189
|
+
| `--no-cache` | flag | Bypass cache and re-parse all files. |
|
|
190
|
+
| `--version` | flag | Show version and exit. |
|
|
191
|
+
| `--help` | flag | Show help message. |
|
|
192
|
+
|
|
193
|
+
### LLM / Agent Integration
|
|
194
|
+
|
|
195
|
+
- **Automatic Agent Discovery via `AGENTS.md`**: Coding agents (Antigravity, Cursor, Claude Code, GitHub Copilot) automatically load `AGENTS.md` at conversation start. By telling the agent to consult `INDEX.md` first, the agent pinpoints definitions immediately without burning tokens on repository-wide grep searches.
|
|
196
|
+
- **Surgical Inspection**: Because each symbol includes `@<line>`, an LLM can request precise lines via tools (e.g. `head -n 50` or view tool slice) rather than ingesting entire files.
|
|
197
|
+
- **Machine-Readable Formats**: Use `--format json` to integrate with custom RAG systems or agent tools:
|
|
198
|
+
|
|
199
|
+
```sh
|
|
200
|
+
$ omph scan --format json -o index.json
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
## Development
|
|
204
|
+
|
|
205
|
+
```sh
|
|
206
|
+
# Install development dependencies
|
|
207
|
+
$ uv sync --dev
|
|
208
|
+
|
|
209
|
+
# Run tests
|
|
210
|
+
$ uv run pytest
|
|
211
|
+
|
|
212
|
+
# Run linter and type checker
|
|
213
|
+
$ uv run ruff check .
|
|
214
|
+
$ uv run mypy src
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
## Related Efforts
|
|
218
|
+
|
|
219
|
+
- [Tree-sitter](https://tree-sitter.github.io/tree-sitter/) - Fast, incremental parsing system used under the hood.
|
|
220
|
+
- [Universal Ctags](https://ctags.io/) - Traditional code indexing system.
|
|
221
|
+
- [Repomix](https://github.com/yamadashy/repomix) - Repository packager for AI context.
|
|
222
|
+
|
|
223
|
+
## Contributing
|
|
224
|
+
|
|
225
|
+
Feel free to dive in! [Open an issue](https://github.com/snui1s/Omphalos/issues/new) or submit a Pull Request.
|
|
226
|
+
|
|
227
|
+
Omphalos follows the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) Code of Conduct.
|
|
228
|
+
|
|
229
|
+
## License
|
|
230
|
+
|
|
231
|
+
[MIT](LICENSE) © 2026 snui1s
|
omphalos-1.1.1/README.md
ADDED
|
@@ -0,0 +1,197 @@
|
|
|
1
|
+
# Omphalos
|
|
2
|
+
|
|
3
|
+
[](https://github.com/RichardLitt/standard-readme)
|
|
4
|
+
[](https://github.com/snui1s/Omphalos/actions/workflows/ci.yml)
|
|
5
|
+
[](https://www.python.org/)
|
|
6
|
+
[](LICENSE)
|
|
7
|
+
|
|
8
|
+
> Codebase symbol indexer for LLMs.
|
|
9
|
+
|
|
10
|
+
Omphalos generates a compact, high-signal symbol map (`INDEX.md`) of your repository. It provides large language models and developers with an instant architectural overview and precise symbol locations—minimizing token usage and eliminating the need to read entire source files just to find declarations.
|
|
11
|
+
|
|
12
|
+
## Table of Contents
|
|
13
|
+
|
|
14
|
+
- [Omphalos](#omphalos)
|
|
15
|
+
- [Table of Contents](#table-of-contents)
|
|
16
|
+
- [Background](#background)
|
|
17
|
+
- [Install](#install)
|
|
18
|
+
- [Usage](#usage)
|
|
19
|
+
- [Quick Start](#quick-start)
|
|
20
|
+
- [CLI Reference](#cli-reference)
|
|
21
|
+
- [LLM / Agent Integration](#llm--agent-integration)
|
|
22
|
+
- [Development](#development)
|
|
23
|
+
- [Related Efforts](#related-efforts)
|
|
24
|
+
- [Maintainers](#maintainers)
|
|
25
|
+
- [Contributing](#contributing)
|
|
26
|
+
- [License](#license)
|
|
27
|
+
|
|
28
|
+
## Background
|
|
29
|
+
|
|
30
|
+
When providing a full codebase as context to Large Language Models (LLMs) or AI coding agents, feeding entire file contents quickly exhausts the model's context window, degrades reasoning performance, and incurs high token costs.
|
|
31
|
+
|
|
32
|
+
In practice, an agent rarely needs the implementation bodies of every file at once; it only needs an accurate structural index: what functions, classes, interfaces, and methods exist, where they are defined, and what their docstrings say.
|
|
33
|
+
|
|
34
|
+
Omphalos was created to solve this problem:
|
|
35
|
+
|
|
36
|
+
1. **Multi-language AST Parsing**: Uses Tree-sitter for deterministic parsing across Python, TypeScript/JavaScript, Go, and Rust.
|
|
37
|
+
2. **Precise Line Numbers (`@<line>`)**: Symbols indicate exact declaration line numbers so agents can inspect or slice specific ranges on demand.
|
|
38
|
+
3. **Internal Logic Hints**: Function-like symbols list their deduplicated call targets (`calls`) and raised exception types (`raises`), giving agents a control-flow preview without opening the file.
|
|
39
|
+
4. **Atomic Incremental Cache**: Tracks SHA-256 content hashes to re-parse only changed files, guaranteeing rapid re-indexes.
|
|
40
|
+
5. **CI/CD Integration**: Supports `--check` mode to ensure codebase indexes stay synchronized with changes.
|
|
41
|
+
|
|
42
|
+
## Install
|
|
43
|
+
|
|
44
|
+
### Using [uv](https://github.com/astral-sh/uv) (Recommended)
|
|
45
|
+
|
|
46
|
+
Run directly without installing:
|
|
47
|
+
|
|
48
|
+
```sh
|
|
49
|
+
$ uvx --from git+https://github.com/snui1s/Omphalos.git omph scan
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Or install as a standalone CLI tool:
|
|
53
|
+
|
|
54
|
+
```sh
|
|
55
|
+
$ uv tool install git+https://github.com/snui1s/Omphalos.git
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
### Using pip
|
|
59
|
+
|
|
60
|
+
```sh
|
|
61
|
+
$ pip install git+https://github.com/snui1s/Omphalos.git
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### Using npm / npx
|
|
65
|
+
|
|
66
|
+
Run directly via npx:
|
|
67
|
+
|
|
68
|
+
```sh
|
|
69
|
+
$ npx omphalos scan
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Or install globally:
|
|
73
|
+
|
|
74
|
+
```sh
|
|
75
|
+
$ npm install -g omphalos
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
### From Source
|
|
79
|
+
|
|
80
|
+
```sh
|
|
81
|
+
$ git clone https://github.com/snui1s/Omphalos.git
|
|
82
|
+
$ cd Omphalos
|
|
83
|
+
$ uv sync
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
## Usage
|
|
87
|
+
|
|
88
|
+
### Quick Start
|
|
89
|
+
|
|
90
|
+
1. **Initialize Ignore File** (creates default `.omphignore`):
|
|
91
|
+
|
|
92
|
+
```sh
|
|
93
|
+
$ omph init
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
2. **Generate the Symbol Index**:
|
|
97
|
+
|
|
98
|
+
```sh
|
|
99
|
+
$ omph scan
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
This generates `INDEX.md` in the root directory:
|
|
103
|
+
|
|
104
|
+
```markdown
|
|
105
|
+
# Codebase Symbol Index
|
|
106
|
+
|
|
107
|
+
## src/omphalos/cache.py
|
|
108
|
+
|
|
109
|
+
- `calculate_sha256()` @15: Calculate the SHA-256 checksum of raw file bytes for change detection. (calls: `hexdigest`, `hashlib.sha256`)
|
|
110
|
+
- `save_cache()` @38: Save symbol cache to .omphcache atomically. (calls: `tempfile.mkstemp`, `os.fdopen`, `json.dump`, `os.replace`, `os.unlink`)
|
|
111
|
+
|
|
112
|
+
## src/omphalos/cli.py
|
|
113
|
+
|
|
114
|
+
- `_version_callback()` @33: Callback for --version flag to print the version and exit immediately. (calls: `typer.echo`, `_package_version`; raises: `typer.Exit`)
|
|
115
|
+
|
|
116
|
+
## tests/fixtures/sample.ts
|
|
117
|
+
|
|
118
|
+
- export interface `UserProfile` @1
|
|
119
|
+
- export type `AuthToken` @6
|
|
120
|
+
- export function `verifyToken()` @8
|
|
121
|
+
- export class `SessionManager` @18
|
|
122
|
+
- `createSession()` @19
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
3. **Instruct AI Agents via `AGENTS.md`**:
|
|
126
|
+
|
|
127
|
+
Create or add to `AGENTS.md` (or `CLAUDE.md` / `.cursorrules`) at the root of your repository so AI agents read `INDEX.md` before exploring code:
|
|
128
|
+
|
|
129
|
+
```markdown
|
|
130
|
+
# Agent Guidelines
|
|
131
|
+
|
|
132
|
+
## Codebase Navigation & Exploration
|
|
133
|
+
|
|
134
|
+
Before searching, running grep, or opening entire source files across the codebase:
|
|
135
|
+
|
|
136
|
+
1. **Always read [`INDEX.md`](INDEX.md) first.** It provides an instant symbol map of the entire repository with exact line numbers.
|
|
137
|
+
2. Use the symbols, line locations (`@<line>`), and internal logic hints (`calls:`, `raises:`) in [`INDEX.md`](INDEX.md) to pinpoint definitions directly.
|
|
138
|
+
3. Inspect or slice-read only the specific line ranges or files needed for the task, rather than loading entire files into context.
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
### CLI Reference
|
|
142
|
+
|
|
143
|
+
```sh
|
|
144
|
+
$ omph scan [DIRECTORY] [OPTIONS]
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
The binary is installed as `omph`; the full name `omphalos` is also available as an alias.
|
|
148
|
+
|
|
149
|
+
| Option | Flag | Description |
|
|
150
|
+
| ---------------- | ------------------ | ------------------------------------------------------------------------- |
|
|
151
|
+
| `--output`, `-o` | `PATH` | Custom path for index output (default: `INDEX.md`). |
|
|
152
|
+
| `--format` | `markdown \| json` | Output format (default: `markdown`). |
|
|
153
|
+
| `--check` | flag | Verify index is up to date without writing. Exits with code `1` if stale. |
|
|
154
|
+
| `--git-only` | flag | Scan only files tracked by Git (`git ls-files`). |
|
|
155
|
+
| `--no-cache` | flag | Bypass cache and re-parse all files. |
|
|
156
|
+
| `--version` | flag | Show version and exit. |
|
|
157
|
+
| `--help` | flag | Show help message. |
|
|
158
|
+
|
|
159
|
+
### LLM / Agent Integration
|
|
160
|
+
|
|
161
|
+
- **Automatic Agent Discovery via `AGENTS.md`**: Coding agents (Antigravity, Cursor, Claude Code, GitHub Copilot) automatically load `AGENTS.md` at conversation start. By telling the agent to consult `INDEX.md` first, the agent pinpoints definitions immediately without burning tokens on repository-wide grep searches.
|
|
162
|
+
- **Surgical Inspection**: Because each symbol includes `@<line>`, an LLM can request precise lines via tools (e.g. `head -n 50` or view tool slice) rather than ingesting entire files.
|
|
163
|
+
- **Machine-Readable Formats**: Use `--format json` to integrate with custom RAG systems or agent tools:
|
|
164
|
+
|
|
165
|
+
```sh
|
|
166
|
+
$ omph scan --format json -o index.json
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
## Development
|
|
170
|
+
|
|
171
|
+
```sh
|
|
172
|
+
# Install development dependencies
|
|
173
|
+
$ uv sync --dev
|
|
174
|
+
|
|
175
|
+
# Run tests
|
|
176
|
+
$ uv run pytest
|
|
177
|
+
|
|
178
|
+
# Run linter and type checker
|
|
179
|
+
$ uv run ruff check .
|
|
180
|
+
$ uv run mypy src
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
## Related Efforts
|
|
184
|
+
|
|
185
|
+
- [Tree-sitter](https://tree-sitter.github.io/tree-sitter/) - Fast, incremental parsing system used under the hood.
|
|
186
|
+
- [Universal Ctags](https://ctags.io/) - Traditional code indexing system.
|
|
187
|
+
- [Repomix](https://github.com/yamadashy/repomix) - Repository packager for AI context.
|
|
188
|
+
|
|
189
|
+
## Contributing
|
|
190
|
+
|
|
191
|
+
Feel free to dive in! [Open an issue](https://github.com/snui1s/Omphalos/issues/new) or submit a Pull Request.
|
|
192
|
+
|
|
193
|
+
Omphalos follows the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) Code of Conduct.
|
|
194
|
+
|
|
195
|
+
## License
|
|
196
|
+
|
|
197
|
+
[MIT](LICENSE) © 2026 snui1s
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "omphalos"
|
|
3
|
+
version = "1.1.1"
|
|
4
|
+
description = "Codebase symbol index for LLMs"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
requires-python = ">=3.10"
|
|
7
|
+
keywords = [
|
|
8
|
+
"llm",
|
|
9
|
+
"indexer",
|
|
10
|
+
"tree-sitter",
|
|
11
|
+
"ast",
|
|
12
|
+
"codebase",
|
|
13
|
+
"symbols",
|
|
14
|
+
"agent",
|
|
15
|
+
]
|
|
16
|
+
classifiers = [
|
|
17
|
+
"Development Status :: 4 - Beta",
|
|
18
|
+
"Environment :: Console",
|
|
19
|
+
"Intended Audience :: Developers",
|
|
20
|
+
"Operating System :: OS Independent",
|
|
21
|
+
"Programming Language :: Python :: 3",
|
|
22
|
+
"Programming Language :: Python :: 3.10",
|
|
23
|
+
"Programming Language :: Python :: 3.11",
|
|
24
|
+
"Programming Language :: Python :: 3.12",
|
|
25
|
+
"Programming Language :: Python :: 3.13",
|
|
26
|
+
"Topic :: Software Development :: Code Generators",
|
|
27
|
+
"Topic :: Software Development :: Libraries :: Python Modules",
|
|
28
|
+
]
|
|
29
|
+
dependencies = [
|
|
30
|
+
"typer>=0.12.0",
|
|
31
|
+
"pathspec>=1.1",
|
|
32
|
+
"tree-sitter>=0.24.0",
|
|
33
|
+
"tree-sitter-python>=0.25.0",
|
|
34
|
+
"tree-sitter-typescript>=0.23.0",
|
|
35
|
+
"tree-sitter-javascript>=0.25.0",
|
|
36
|
+
"tree-sitter-go>=0.25.0",
|
|
37
|
+
"tree-sitter-rust>=0.24.0",
|
|
38
|
+
]
|
|
39
|
+
|
|
40
|
+
[[project.authors]]
|
|
41
|
+
name = "snui1s"
|
|
42
|
+
email = "snailsqz@gmail.com"
|
|
43
|
+
|
|
44
|
+
[project.license]
|
|
45
|
+
text = "MIT"
|
|
46
|
+
|
|
47
|
+
[project.urls]
|
|
48
|
+
Homepage = "https://github.com/snui1s/Omphalos"
|
|
49
|
+
Repository = "https://github.com/snui1s/Omphalos"
|
|
50
|
+
Issues = "https://github.com/snui1s/Omphalos/issues"
|
|
51
|
+
Changelog = "https://github.com/snui1s/Omphalos/releases"
|
|
52
|
+
|
|
53
|
+
[project.scripts]
|
|
54
|
+
omph = "omphalos.cli:app"
|
|
55
|
+
omphalos = "omphalos.cli:app"
|
|
56
|
+
|
|
57
|
+
[dependency-groups]
|
|
58
|
+
dev = [
|
|
59
|
+
"pytest>=8.0",
|
|
60
|
+
"ruff>=0.8",
|
|
61
|
+
"mypy>=1.13",
|
|
62
|
+
]
|
|
63
|
+
|
|
64
|
+
[tool.ruff]
|
|
65
|
+
line-length = 120
|
|
66
|
+
target-version = "py310"
|
|
67
|
+
|
|
68
|
+
[tool.ruff.lint]
|
|
69
|
+
select = [
|
|
70
|
+
"E",
|
|
71
|
+
"F",
|
|
72
|
+
"W",
|
|
73
|
+
"I",
|
|
74
|
+
"UP",
|
|
75
|
+
"B",
|
|
76
|
+
]
|
|
77
|
+
|
|
78
|
+
[tool.ruff.lint.per-file-ignores]
|
|
79
|
+
"src/omphalos/cli.py" = ["B008"]
|
|
80
|
+
|
|
81
|
+
[tool.mypy]
|
|
82
|
+
python_version = "3.10"
|
|
83
|
+
warn_unused_ignores = true
|
|
84
|
+
warn_redundant_casts = true
|
|
85
|
+
no_implicit_optional = true
|
|
86
|
+
|
|
87
|
+
[[tool.mypy.overrides]]
|
|
88
|
+
module = [
|
|
89
|
+
"tree_sitter_python",
|
|
90
|
+
"tree_sitter_typescript",
|
|
91
|
+
"tree_sitter_javascript",
|
|
92
|
+
"tree_sitter_go",
|
|
93
|
+
"tree_sitter_rust",
|
|
94
|
+
]
|
|
95
|
+
ignore_missing_imports = true
|
|
96
|
+
|
|
97
|
+
[build-system]
|
|
98
|
+
requires = ["uv_build>=0.12.5,<0.13.0"]
|
|
99
|
+
build-backend = "uv_build"
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "omphalos"
|
|
3
|
+
version = "1.1.1"
|
|
4
|
+
description = "Codebase symbol index for LLMs"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
authors = [
|
|
7
|
+
{ name = "snui1s", email = "snailsqz@gmail.com" }
|
|
8
|
+
]
|
|
9
|
+
requires-python = ">=3.10"
|
|
10
|
+
license = { text = "MIT" }
|
|
11
|
+
keywords = ["llm", "indexer", "tree-sitter", "ast", "codebase", "symbols", "agent"]
|
|
12
|
+
classifiers = [
|
|
13
|
+
"Development Status :: 4 - Beta",
|
|
14
|
+
"Environment :: Console",
|
|
15
|
+
"Intended Audience :: Developers",
|
|
16
|
+
"Operating System :: OS Independent",
|
|
17
|
+
"Programming Language :: Python :: 3",
|
|
18
|
+
"Programming Language :: Python :: 3.10",
|
|
19
|
+
"Programming Language :: Python :: 3.11",
|
|
20
|
+
"Programming Language :: Python :: 3.12",
|
|
21
|
+
"Programming Language :: Python :: 3.13",
|
|
22
|
+
"Topic :: Software Development :: Code Generators",
|
|
23
|
+
"Topic :: Software Development :: Libraries :: Python Modules",
|
|
24
|
+
]
|
|
25
|
+
dependencies = [
|
|
26
|
+
"typer>=0.12.0",
|
|
27
|
+
"pathspec>=1.1",
|
|
28
|
+
"tree-sitter>=0.24.0",
|
|
29
|
+
"tree-sitter-python>=0.25.0",
|
|
30
|
+
"tree-sitter-typescript>=0.23.0",
|
|
31
|
+
"tree-sitter-javascript>=0.25.0",
|
|
32
|
+
"tree-sitter-go>=0.25.0",
|
|
33
|
+
"tree-sitter-rust>=0.24.0",
|
|
34
|
+
]
|
|
35
|
+
|
|
36
|
+
[project.urls]
|
|
37
|
+
Homepage = "https://github.com/snui1s/Omphalos"
|
|
38
|
+
Repository = "https://github.com/snui1s/Omphalos"
|
|
39
|
+
Issues = "https://github.com/snui1s/Omphalos/issues"
|
|
40
|
+
Changelog = "https://github.com/snui1s/Omphalos/releases"
|
|
41
|
+
|
|
42
|
+
[project.scripts]
|
|
43
|
+
omph = "omphalos.cli:app"
|
|
44
|
+
omphalos = "omphalos.cli:app"
|
|
45
|
+
|
|
46
|
+
[dependency-groups]
|
|
47
|
+
dev = [
|
|
48
|
+
"pytest>=8.0",
|
|
49
|
+
"ruff>=0.8",
|
|
50
|
+
"mypy>=1.13",
|
|
51
|
+
]
|
|
52
|
+
|
|
53
|
+
[tool.ruff]
|
|
54
|
+
line-length = 120
|
|
55
|
+
target-version = "py310"
|
|
56
|
+
|
|
57
|
+
[tool.ruff.lint]
|
|
58
|
+
select = ["E", "F", "W", "I", "UP", "B"]
|
|
59
|
+
|
|
60
|
+
[tool.ruff.lint.per-file-ignores]
|
|
61
|
+
# B008: typer.Option(...) เป็น idiom มาตรฐานของ Typer
|
|
62
|
+
"src/omphalos/cli.py" = ["B008"]
|
|
63
|
+
|
|
64
|
+
[tool.mypy]
|
|
65
|
+
python_version = "3.10"
|
|
66
|
+
warn_unused_ignores = true
|
|
67
|
+
warn_redundant_casts = true
|
|
68
|
+
no_implicit_optional = true
|
|
69
|
+
|
|
70
|
+
[[tool.mypy.overrides]]
|
|
71
|
+
module = ["tree_sitter_python", "tree_sitter_typescript", "tree_sitter_javascript", "tree_sitter_go", "tree_sitter_rust"]
|
|
72
|
+
ignore_missing_imports = true
|
|
73
|
+
|
|
74
|
+
[build-system]
|
|
75
|
+
requires = ["uv_build>=0.12.5,<0.13.0"]
|
|
76
|
+
build-backend = "uv_build"
|
|
File without changes
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
# omphalos/cache.py
|
|
2
|
+
import hashlib
|
|
3
|
+
import json
|
|
4
|
+
import os
|
|
5
|
+
import tempfile
|
|
6
|
+
from pathlib import Path
|
|
7
|
+
|
|
8
|
+
CACHE_FILE = ".omphcache"
|
|
9
|
+
# Increment this number when the cache data structure changes to invalidate old caches.
|
|
10
|
+
# v3: symbols stored as structured dicts (kind/name/line/doc/label/children)
|
|
11
|
+
# v4: function/method symbols gained optional `calls` and `raises` lists
|
|
12
|
+
# v5: calls exclude signature/decorator/defaults and collapse chained callees
|
|
13
|
+
CACHE_VERSION = 5
|
|
14
|
+
|
|
15
|
+
def calculate_sha256(content: bytes) -> str:
|
|
16
|
+
"""Calculate the SHA-256 checksum of raw file bytes for change detection."""
|
|
17
|
+
return hashlib.sha256(content).hexdigest()
|
|
18
|
+
|
|
19
|
+
def load_cache(root_dir: Path) -> dict:
|
|
20
|
+
"""Load symbol cache from .omphcache.
|
|
21
|
+
|
|
22
|
+
Returns an empty dict if the cache file does not exist, fails to parse,
|
|
23
|
+
or has an incompatible cache version.
|
|
24
|
+
"""
|
|
25
|
+
cache_path = root_dir / CACHE_FILE
|
|
26
|
+
if not cache_path.exists():
|
|
27
|
+
return {}
|
|
28
|
+
try:
|
|
29
|
+
raw = json.loads(cache_path.read_text(encoding="utf-8"))
|
|
30
|
+
except (json.JSONDecodeError, UnicodeDecodeError, OSError):
|
|
31
|
+
return {}
|
|
32
|
+
# Discard cache created with a different schema version
|
|
33
|
+
if not isinstance(raw, dict) or raw.get("version") != CACHE_VERSION:
|
|
34
|
+
return {}
|
|
35
|
+
files = raw.get("files")
|
|
36
|
+
return files if isinstance(files, dict) else {}
|
|
37
|
+
|
|
38
|
+
def save_cache(root_dir: Path, cache: dict):
|
|
39
|
+
"""Save symbol cache to .omphcache atomically.
|
|
40
|
+
|
|
41
|
+
Writes to a temporary file first and replaces the target file via os.replace
|
|
42
|
+
to prevent file corruption if interrupted.
|
|
43
|
+
"""
|
|
44
|
+
cache_path = root_dir / CACHE_FILE
|
|
45
|
+
payload = {"version": CACHE_VERSION, "files": cache}
|
|
46
|
+
fd, tmp_name = tempfile.mkstemp(
|
|
47
|
+
dir=cache_path.parent, prefix=f"{CACHE_FILE}.", suffix=".tmp"
|
|
48
|
+
)
|
|
49
|
+
try:
|
|
50
|
+
with os.fdopen(fd, "w", encoding="utf-8") as f:
|
|
51
|
+
json.dump(payload, f, indent=2, ensure_ascii=False)
|
|
52
|
+
os.replace(tmp_name, cache_path)
|
|
53
|
+
except BaseException:
|
|
54
|
+
try:
|
|
55
|
+
os.unlink(tmp_name)
|
|
56
|
+
except OSError:
|
|
57
|
+
pass
|
|
58
|
+
raise
|