combicode 4.0.0__py3-none-win_arm64.whl
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.
|
Binary file
|
|
@@ -0,0 +1,229 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: combicode
|
|
3
|
+
Version: 4.0.0
|
|
4
|
+
Summary: Pack a codebase into one LLM-friendly text file with a code map and exact line references
|
|
5
|
+
Author: A. Aurelions
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
License-File: LICENSE
|
|
8
|
+
Project-URL: Homepage, https://github.com/aaurelions/combicode
|
|
9
|
+
Project-URL: Issues, https://github.com/aaurelions/combicode/issues
|
|
10
|
+
Keywords: llm,context,prompt,cli,codebase
|
|
11
|
+
Classifier: Environment :: Console
|
|
12
|
+
Classifier: Topic :: Software Development
|
|
13
|
+
Description-Content-Type: text/markdown
|
|
14
|
+
|
|
15
|
+
# Combicode
|
|
16
|
+
|
|
17
|
+
[](https://crates.io/crates/combicode)
|
|
18
|
+
[](https://www.npmjs.com/package/combicode)
|
|
19
|
+
[](https://pypi.org/project/combicode/)
|
|
20
|
+
[](LICENSE)
|
|
21
|
+
|
|
22
|
+
Combicode packs a project into one text file that you can give to an LLM. The file contains:
|
|
23
|
+
|
|
24
|
+
1. **A prompt** that tells the model what it is reading.
|
|
25
|
+
2. **A code map**: the directory tree plus the classes and functions in each file, with line numbers and sizes.
|
|
26
|
+
3. **The code**: every file, unchanged.
|
|
27
|
+
|
|
28
|
+
Every line number in the map is exact, so you and the model can jump straight to any file or function.
|
|
29
|
+
|
|
30
|
+
Combicode is a single native binary written in Rust. The npm and PyPI packages contain the same binary, so you do not need Rust, Node.js or Python beyond the tool you install it with.
|
|
31
|
+
|
|
32
|
+
## Install
|
|
33
|
+
|
|
34
|
+
| Tool | Run once | Install |
|
|
35
|
+
| --- | --- | --- |
|
|
36
|
+
| npm | `npx combicode` | `npm install -g combicode` |
|
|
37
|
+
| Python | `uvx combicode` or `pipx run combicode` | `pipx install combicode` or `pip install combicode` |
|
|
38
|
+
| Homebrew | | `brew install aaurelions/tap/combicode` |
|
|
39
|
+
| Cargo | | `cargo install combicode` |
|
|
40
|
+
|
|
41
|
+
`npx combicode` needs only Node.js 18 or newer: npm downloads the prebuilt binary for your platform (Linux, macOS or Windows on x64 or ARM64) as an optional dependency. On other platforms, or if optional dependencies are disabled (`--omit=optional`), use `cargo install combicode`.
|
|
42
|
+
|
|
43
|
+
Prebuilt binaries for Linux, macOS and Windows (x64 and ARM64) are attached to every [GitHub release](https://github.com/aaurelions/combicode/releases).
|
|
44
|
+
|
|
45
|
+
## Usage
|
|
46
|
+
|
|
47
|
+
Run it in your project directory:
|
|
48
|
+
|
|
49
|
+
```sh
|
|
50
|
+
combicode # saves combicode.txt
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
When you run it in a terminal, Combicode saves `combicode.txt`. When its output is redirected or piped, it writes to stdout instead, so both of these work:
|
|
54
|
+
|
|
55
|
+
```sh
|
|
56
|
+
combicode > combicode.txt
|
|
57
|
+
combicode | pbcopy # copy to the clipboard on macOS
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Status messages go to stderr, so they never end up in the file.
|
|
61
|
+
|
|
62
|
+
### Choose what goes into the file
|
|
63
|
+
|
|
64
|
+
```sh
|
|
65
|
+
combicode --no-prompt > no-prompt.txt # map and code, without the prompt
|
|
66
|
+
combicode --no-prompt --no-code > map.txt # only the map
|
|
67
|
+
combicode --only-map > map.txt # the same, shorter
|
|
68
|
+
combicode --only-map --no-size > map.txt # the map without sizes
|
|
69
|
+
combicode --no-map -o no-map.txt # prompt and code, without the map
|
|
70
|
+
combicode --no-outline # the map lists files but not functions
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### Choose which files to pack
|
|
74
|
+
|
|
75
|
+
```sh
|
|
76
|
+
combicode --include 'src/,*.md' # only src/ and Markdown files
|
|
77
|
+
combicode --only-map --include 'hello,world,my.txt' -o combicode.txt
|
|
78
|
+
combicode --exclude '*.test.ts,fixtures/' # skip more files
|
|
79
|
+
combicode --omit-content 'data/,*.csv' # list these in the map, but leave out their content
|
|
80
|
+
combicode ../other-project -o other.txt # pack another directory
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Patterns use [gitignore syntax](https://git-scm.com/docs/gitignore#_pattern_format). A pattern without a slash, such as `hello` or `*.md`, matches at any depth, and a directory pattern matches everything inside it. Separate patterns with commas or repeat the option: `-i src/ -i '*.md'`.
|
|
84
|
+
|
|
85
|
+
## Output
|
|
86
|
+
|
|
87
|
+
For a small project, `combicode` produces this file (line numbers added for reference):
|
|
88
|
+
|
|
89
|
+
```text
|
|
90
|
+
1 You are given the source code of the project "my-app", packed into a single document by Combicode.
|
|
91
|
+
2
|
|
92
|
+
3 <code_map> lists every included file as a directory tree, with the classes, functions and other symbols found in each file. Entries show OL (line range in the original file), ML (line range in this document) and size. <code> contains the files in map order, each inside a <file path="..."> element exactly as it appears on disk.
|
|
93
|
+
4
|
|
94
|
+
5 Before answering, study the project as a whole: its structure, entry points, configuration, dependencies and how the parts interact. When you refer to code, cite the file path and original line numbers. Use ML ranges to find a file or symbol in this document.
|
|
95
|
+
6
|
|
96
|
+
7 <code_map>
|
|
97
|
+
8 my-app/
|
|
98
|
+
9 ├── package.json [OL: 1-4 | ML: 18-21 | 43B]
|
|
99
|
+
10 └── src/
|
|
100
|
+
11 ├── greet.js [OL: 1-3 | ML: 25-27 | 60B]
|
|
101
|
+
12 │ └── fn greet(name) [OL: 1-3 | ML: 25-27 | 60B]
|
|
102
|
+
13 └── index.js [OL: 1-3 | ML: 31-33 | 66B]
|
|
103
|
+
14 </code_map>
|
|
104
|
+
15
|
|
105
|
+
16 <code>
|
|
106
|
+
17 <file path="package.json" bytes="43">
|
|
107
|
+
18 {
|
|
108
|
+
19 "name": "my-app",
|
|
109
|
+
20 "type": "module"
|
|
110
|
+
21 }
|
|
111
|
+
22 </file>
|
|
112
|
+
23
|
|
113
|
+
24 <file path="src/greet.js" bytes="60">
|
|
114
|
+
25 export function greet(name) {
|
|
115
|
+
26 return `Hello, ${name}!`;
|
|
116
|
+
27 }
|
|
117
|
+
28 </file>
|
|
118
|
+
29
|
|
119
|
+
30 <file path="src/index.js" bytes="66">
|
|
120
|
+
31 import { greet } from "./greet.js";
|
|
121
|
+
32
|
|
122
|
+
33 console.log(greet("world"));
|
|
123
|
+
34 </file>
|
|
124
|
+
35 </code>
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Each map entry shows:
|
|
128
|
+
|
|
129
|
+
- **OL** (original lines): the line range in the source file. `fn greet(name) [OL: 1-3]` is lines 1–3 of `greet.js`.
|
|
130
|
+
- **ML** (merged lines): the line range in the output file, so `sed -n '25,27p' combicode.txt` prints exactly `greet`. ML appears only when the code is included.
|
|
131
|
+
- **Size** of the file or symbol. Hide it with `--no-size`.
|
|
132
|
+
|
|
133
|
+
Lines are counted by `\n`, the same way as `sed`, `wc -l` and editors. Windows line endings (`\r\n`) do not change the count. Empty files are shown as `[empty]`, and files left out with `--omit-content` as `[content omitted | size]`.
|
|
134
|
+
|
|
135
|
+
The map is a *code map*: a directory **tree** with an **outline** of each file. That is why the options are named `--no-map`, `--only-map` and `--no-outline`.
|
|
136
|
+
|
|
137
|
+
### Outlines
|
|
138
|
+
|
|
139
|
+
The outline lists classes, structs, interfaces, functions, methods, test cases and long loops (6 lines or more) for:
|
|
140
|
+
|
|
141
|
+
| Languages | Extensions |
|
|
142
|
+
| --- | --- |
|
|
143
|
+
| Python | `.py` `.pyi` |
|
|
144
|
+
| JavaScript, TypeScript | `.js` `.jsx` `.mjs` `.cjs` `.ts` `.tsx` `.mts` `.cts` |
|
|
145
|
+
| Rust, Go | `.rs` `.go` |
|
|
146
|
+
| C, C++, C#, Java | `.c` `.h` `.cc` `.cpp` `.cxx` `.hh` `.hpp` `.hxx` `.cs` `.java` |
|
|
147
|
+
| Kotlin, Swift, Scala | `.kt` `.kts` `.swift` `.scala` `.sc` |
|
|
148
|
+
| PHP, Ruby, Lua, Perl, shell | `.php` `.rb` `.lua` `.pl` `.pm` `.sh` `.bash` `.zsh` |
|
|
149
|
+
|
|
150
|
+
Other text files are included without an outline. Outlines are found with fast heuristics rather than a full parser: they skip comments and strings and handle multi-line signatures, but unusual syntax can be missed. File contents are never changed.
|
|
151
|
+
|
|
152
|
+
### Prompts
|
|
153
|
+
|
|
154
|
+
```sh
|
|
155
|
+
combicode --prompt docs -i '*.md' -o docs.txt # a prompt for documentation (llms.txt style)
|
|
156
|
+
combicode --prompt-file my-prompt.md # your own prompt
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
The built-in prompts describe only the sections that are present. `--prompt docs` tells the model to answer strictly from the packed documents.
|
|
160
|
+
|
|
161
|
+
## Which files are included
|
|
162
|
+
|
|
163
|
+
Combicode walks the directory and:
|
|
164
|
+
|
|
165
|
+
- respects `.gitignore` (including nested ones, `.git/info/exclude` and your global gitignore) and `.ignore` files. Use `--no-gitignore` to turn this off;
|
|
166
|
+
- respects a `.combicodeignore` file, in gitignore syntax, for project-specific rules that should not affect git;
|
|
167
|
+
- skips [common non-source files](src/defaults.gitignore): `.git`, dependencies such as `node_modules` and `.venv`, build output such as `target` and `dist`, lockfiles, `.env` files, media and archives. `--no-gitignore` does not turn these off;
|
|
168
|
+
- skips git submodules, symlinks, binary files and files that are not valid UTF-8 (with a warning);
|
|
169
|
+
- never packs its own output file, or an earlier Combicode output lying in the project.
|
|
170
|
+
|
|
171
|
+
Ignore rules are not secret detection. Check the file before you share it.
|
|
172
|
+
|
|
173
|
+
## Restore files
|
|
174
|
+
|
|
175
|
+
A Combicode file can be turned back into files:
|
|
176
|
+
|
|
177
|
+
```sh
|
|
178
|
+
combicode restore combicode.txt -o restored/ # recreate the files in restored/
|
|
179
|
+
combicode restore combicode.txt -o restored/ -n # dry run: show what would be written
|
|
180
|
+
combicode restore combicode.txt --force # replace files that already exist
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
The `bytes` attribute of each `<file>` element is the exact UTF-8 length of its content, so content that looks like a `</file>` tag, empty files, missing final newlines, `\r\n` line endings and Unicode all round-trip exactly. If you edit content inside the file, update `bytes` to match.
|
|
184
|
+
|
|
185
|
+
Restore never writes outside the target directory: absolute paths, `..`, symlinks, Windows device names and other unsafe paths are rejected before anything is written. Existing files are kept unless you pass `--force`, and replaced files are swapped in atomically. Files left out with `--omit-content` are not restored.
|
|
186
|
+
|
|
187
|
+
## Options
|
|
188
|
+
|
|
189
|
+
```text
|
|
190
|
+
combicode [OPTIONS] [PATH]
|
|
191
|
+
combicode restore [OPTIONS] [INPUT]
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
| Option | Description |
|
|
195
|
+
| --- | --- |
|
|
196
|
+
| `PATH` | Project directory to pack. Default: the current directory. |
|
|
197
|
+
| `-o, --output <FILE>` | Write to `FILE`; `-` means stdout. Default: stdout, or `combicode.txt` when stdout is a terminal. |
|
|
198
|
+
| `-i, --include <PATTERNS>` | Pack only files matching these patterns. |
|
|
199
|
+
| `-e, --exclude <PATTERNS>` | Skip files matching these patterns. |
|
|
200
|
+
| `--omit-content <PATTERNS>` | List matching files in the map without their content. |
|
|
201
|
+
| `--no-gitignore` | Do not read `.gitignore`, `.ignore` or git exclude files. |
|
|
202
|
+
| `--no-prompt` | Leave out the prompt. |
|
|
203
|
+
| `--no-map` | Leave out the code map. |
|
|
204
|
+
| `--no-code` | Leave out file contents. |
|
|
205
|
+
| `--only-map` | Output only the code map (`--no-prompt --no-code`). |
|
|
206
|
+
| `--no-outline` | List files in the map without classes and functions. |
|
|
207
|
+
| `--no-size` | Hide sizes in the map. |
|
|
208
|
+
| `--prompt <code\|docs>` | Built-in prompt. Default: `code`. |
|
|
209
|
+
| `--prompt-file <FILE>` | Use the contents of `FILE` as the prompt. |
|
|
210
|
+
| `-q, --quiet` | Do not print the summary and warnings. |
|
|
211
|
+
| `-h, --help` / `-V, --version` | Print help or the version. |
|
|
212
|
+
|
|
213
|
+
`restore` options:
|
|
214
|
+
|
|
215
|
+
| Option | Description |
|
|
216
|
+
| --- | --- |
|
|
217
|
+
| `INPUT` | Combicode file to read; `-` means stdin. Default: `combicode.txt`. |
|
|
218
|
+
| `-o, --output <DIR>` | Directory to restore into. Default: the current directory. |
|
|
219
|
+
| `-n, --dry-run` | Show what would be written without changing anything. |
|
|
220
|
+
| `-f, --force` | Replace files that already exist. |
|
|
221
|
+
| `-q, --quiet` | Do not print the file list and summary. |
|
|
222
|
+
|
|
223
|
+
Exit status is 0 on success, 1 on errors and 2 on invalid options.
|
|
224
|
+
|
|
225
|
+
> **Windows PowerShell 5.1** saves redirected output as UTF-16. Use `-o combicode.txt` instead of `>` there (PowerShell 7 is fine).
|
|
226
|
+
|
|
227
|
+
## License
|
|
228
|
+
|
|
229
|
+
[MIT](LICENSE)
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
combicode-4.0.0.data/scripts/combicode.exe,sha256=lOwxwm3z8huLqONb0oweHlGXw8b7RVFhsaWOllXo7FY,1803776
|
|
2
|
+
combicode-4.0.0.dist-info/METADATA,sha256=Hcl5TWXFRbxCGqhZ8HpQD3J4OdWDpoUx6UMd-NVisbw,10935
|
|
3
|
+
combicode-4.0.0.dist-info/WHEEL,sha256=LGQnMEXwU_MhbyW9llMX_KHXgIGI_L5FwhDweEQAAEo,98
|
|
4
|
+
combicode-4.0.0.dist-info/licenses/LICENSE,sha256=e8IIbEqW3WLcZi3L896xdvJSTi9G9GR1qoUe2aIxwj8,1069
|
|
5
|
+
combicode-4.0.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 A. Aurelions
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|