codeshave 0.1.0__py3-none-any.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.
- codeshave/__init__.py +24 -0
- codeshave/__main__.py +8 -0
- codeshave/cli.py +270 -0
- codeshave/clipboard.py +77 -0
- codeshave/estimator.py +68 -0
- codeshave/formatters.py +85 -0
- codeshave/graph.py +75 -0
- codeshave/mcp.py +153 -0
- codeshave/parser.py +179 -0
- codeshave-0.1.0.dist-info/METADATA +158 -0
- codeshave-0.1.0.dist-info/RECORD +14 -0
- codeshave-0.1.0.dist-info/WHEEL +5 -0
- codeshave-0.1.0.dist-info/entry_points.txt +2 -0
- codeshave-0.1.0.dist-info/top_level.txt +1 -0
codeshave/__init__.py
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
"""
|
|
2
|
+
CodeShave
|
|
3
|
+
============
|
|
4
|
+
High-speed, zero-loss AST code context compressor for AI coding assistants and LLMs.
|
|
5
|
+
Reduces prompt tokens by 60-80% while retaining 100% syntactically valid Python code.
|
|
6
|
+
|
|
7
|
+
Author: Jaideep Krishna A (@jaideepkrishna2008-ui)
|
|
8
|
+
License: MIT
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from codeshave.parser import compress_source, extract_symbols
|
|
12
|
+
from codeshave.estimator import estimate_tokens, compute_savings
|
|
13
|
+
from codeshave.graph import DependencyResolver
|
|
14
|
+
from codeshave.formatters import format_bundle
|
|
15
|
+
|
|
16
|
+
__version__ = "0.1.0"
|
|
17
|
+
__all__ = [
|
|
18
|
+
"compress_source",
|
|
19
|
+
"extract_symbols",
|
|
20
|
+
"estimate_tokens",
|
|
21
|
+
"compute_savings",
|
|
22
|
+
"DependencyResolver",
|
|
23
|
+
"format_bundle",
|
|
24
|
+
]
|
codeshave/__main__.py
ADDED
codeshave/cli.py
ADDED
|
@@ -0,0 +1,270 @@
|
|
|
1
|
+
"""
|
|
2
|
+
CLI interface for CodeShave.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
from __future__ import annotations
|
|
6
|
+
|
|
7
|
+
import argparse
|
|
8
|
+
import sys
|
|
9
|
+
import time
|
|
10
|
+
from pathlib import Path
|
|
11
|
+
from typing import List
|
|
12
|
+
|
|
13
|
+
from codeshave import __version__
|
|
14
|
+
from codeshave.clipboard import copy_to_clipboard
|
|
15
|
+
from codeshave.estimator import compute_savings, estimate_tokens
|
|
16
|
+
from codeshave.formatters import FileContextItem, format_bundle
|
|
17
|
+
from codeshave.graph import DependencyResolver
|
|
18
|
+
from codeshave.mcp import run_mcp_server
|
|
19
|
+
from codeshave.parser import compress_source
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
DEFAULT_EXCLUDES = {
|
|
23
|
+
".git",
|
|
24
|
+
".venv",
|
|
25
|
+
"venv",
|
|
26
|
+
"env",
|
|
27
|
+
"__pycache__",
|
|
28
|
+
".pytest_cache",
|
|
29
|
+
".mypy_cache",
|
|
30
|
+
".ruff_cache",
|
|
31
|
+
"build",
|
|
32
|
+
"dist",
|
|
33
|
+
"node_modules",
|
|
34
|
+
"tests",
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def find_python_files(target: Path, excludes: set[str]) -> List[Path]:
|
|
39
|
+
"""Recursively finds all Python files excluding common build/test folders."""
|
|
40
|
+
if target.is_file():
|
|
41
|
+
return [target]
|
|
42
|
+
|
|
43
|
+
found: List[Path] = []
|
|
44
|
+
for p in sorted(target.rglob("*.py")):
|
|
45
|
+
parts = set(p.parts)
|
|
46
|
+
if parts.intersection(excludes):
|
|
47
|
+
continue
|
|
48
|
+
found.append(p)
|
|
49
|
+
return found
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
def handle_pack(args: argparse.Namespace) -> int:
|
|
53
|
+
target = Path(args.path).resolve()
|
|
54
|
+
if not target.exists():
|
|
55
|
+
sys.stderr.write(f"Error: Target path '{args.path}' does not exist.\n")
|
|
56
|
+
return 1
|
|
57
|
+
|
|
58
|
+
start_time = time.perf_counter()
|
|
59
|
+
excludes = DEFAULT_EXCLUDES.copy()
|
|
60
|
+
if args.exclude:
|
|
61
|
+
for ex in args.exclude.split(","):
|
|
62
|
+
excludes.add(ex.strip())
|
|
63
|
+
|
|
64
|
+
files = find_python_files(target, excludes)
|
|
65
|
+
if not files:
|
|
66
|
+
sys.stderr.write("No Python files found to process.\n")
|
|
67
|
+
return 1
|
|
68
|
+
|
|
69
|
+
# Dependency resolution ordering
|
|
70
|
+
if target.is_dir() and not args.no_sort:
|
|
71
|
+
resolver = DependencyResolver(target)
|
|
72
|
+
files = resolver.sort_files_by_dependency(files)
|
|
73
|
+
|
|
74
|
+
items: List[FileContextItem] = []
|
|
75
|
+
total_orig_tokens = 0
|
|
76
|
+
total_comp_tokens = 0
|
|
77
|
+
|
|
78
|
+
if args.stats or not args.output:
|
|
79
|
+
sys.stderr.write(f"\nā” CodeShave v{__version__} ā AST Structural Compressor\n")
|
|
80
|
+
sys.stderr.write(f"Scanning: {target}\n\n")
|
|
81
|
+
header = f"{'FILE':<45} {'ORIGINAL':<12} {'SKELETON':<12} {'SAVINGS':<10}"
|
|
82
|
+
sys.stderr.write(header + "\n")
|
|
83
|
+
sys.stderr.write("ā" * len(header) + "\n")
|
|
84
|
+
|
|
85
|
+
for f in files:
|
|
86
|
+
rel_path = f.relative_to(target) if target.is_dir() else f.name
|
|
87
|
+
try:
|
|
88
|
+
content = f.read_text(encoding="utf-8")
|
|
89
|
+
compressed = compress_source(
|
|
90
|
+
content,
|
|
91
|
+
preserve_docstrings=not args.no_docs,
|
|
92
|
+
preserve_private=not args.no_private,
|
|
93
|
+
)
|
|
94
|
+
orig_t = estimate_tokens(content)
|
|
95
|
+
comp_t = estimate_tokens(compressed)
|
|
96
|
+
|
|
97
|
+
total_orig_tokens += orig_t
|
|
98
|
+
total_comp_tokens += comp_t
|
|
99
|
+
|
|
100
|
+
items.append(
|
|
101
|
+
FileContextItem(
|
|
102
|
+
relative_path=str(rel_path).replace("\\", "/"),
|
|
103
|
+
original_code=content,
|
|
104
|
+
compressed_code=compressed,
|
|
105
|
+
original_tokens=orig_t,
|
|
106
|
+
compressed_tokens=comp_t,
|
|
107
|
+
)
|
|
108
|
+
)
|
|
109
|
+
|
|
110
|
+
pct = ((1.0 - comp_t / orig_t) * 100.0) if orig_t > 0 else 0.0
|
|
111
|
+
if args.stats or not args.output:
|
|
112
|
+
path_str = str(rel_path).replace("\\", "/")
|
|
113
|
+
if len(path_str) > 43:
|
|
114
|
+
path_str = "..." + path_str[-40:]
|
|
115
|
+
sys.stderr.write(
|
|
116
|
+
f"{path_str:<45} {orig_t:>8,} t {comp_t:>8,} t {pct:>8.1f}%\n"
|
|
117
|
+
)
|
|
118
|
+
except Exception as exc:
|
|
119
|
+
sys.stderr.write(f"Skipping {rel_path}: {exc}\n")
|
|
120
|
+
|
|
121
|
+
elapsed_ms = (time.perf_counter() - start_time) * 1000.0
|
|
122
|
+
saved = max(0, total_orig_tokens - total_comp_tokens)
|
|
123
|
+
overall_pct = (saved / total_orig_tokens * 100.0) if total_orig_tokens > 0 else 0.0
|
|
124
|
+
dollars_saved = (saved / 1_000_000.0) * 3.00
|
|
125
|
+
|
|
126
|
+
if args.stats or not args.output:
|
|
127
|
+
sys.stderr.write("ā" * len(header) + "\n")
|
|
128
|
+
sys.stderr.write(
|
|
129
|
+
f"TOTALS ({len(items)} files in {elapsed_ms:.1f}ms):\n"
|
|
130
|
+
f" ⢠Original: {total_orig_tokens:,} tokens\n"
|
|
131
|
+
f" ⢠Compressed: {total_comp_tokens:,} tokens\n"
|
|
132
|
+
f" ⢠Reduction: {saved:,} tokens saved ({overall_pct:.1f}% savings)\n"
|
|
133
|
+
f" ⢠Est. Value: ${dollars_saved:.4f} per prompt call\n\n"
|
|
134
|
+
)
|
|
135
|
+
|
|
136
|
+
bundled = format_bundle(items, output_format=args.format)
|
|
137
|
+
|
|
138
|
+
if args.output:
|
|
139
|
+
out_p = Path(args.output).resolve()
|
|
140
|
+
out_p.parent.mkdir(parents=True, exist_ok=True)
|
|
141
|
+
out_p.write_text(bundled, encoding="utf-8")
|
|
142
|
+
sys.stderr.write(f"ā Bundle saved successfully to: {out_p}\n")
|
|
143
|
+
else:
|
|
144
|
+
sys.stdout.write(bundled)
|
|
145
|
+
|
|
146
|
+
return 0
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
def handle_clip(args: argparse.Namespace) -> int:
|
|
150
|
+
"""Compresses file or directory and copies directly to OS clipboard."""
|
|
151
|
+
target = Path(args.path).resolve()
|
|
152
|
+
if not target.exists():
|
|
153
|
+
sys.stderr.write(f"Error: Target path '{args.path}' does not exist.\n")
|
|
154
|
+
return 1
|
|
155
|
+
|
|
156
|
+
if target.is_file():
|
|
157
|
+
content = target.read_text(encoding="utf-8")
|
|
158
|
+
compressed = compress_source(content, preserve_docstrings=not args.no_docs)
|
|
159
|
+
report = compute_savings(content, compressed)
|
|
160
|
+
formatted = f"# File: {target.name}\n```python\n{compressed}\n```\n"
|
|
161
|
+
copied = copy_to_clipboard(formatted)
|
|
162
|
+
if copied:
|
|
163
|
+
sys.stderr.write(
|
|
164
|
+
f"ā Copied to clipboard! {report.summary_line()} "
|
|
165
|
+
f"(-{report.reduction_percentage:.1f}%)\n"
|
|
166
|
+
f"Ready to paste into ChatGPT, Claude, or Cursor.\n"
|
|
167
|
+
)
|
|
168
|
+
return 0
|
|
169
|
+
else:
|
|
170
|
+
sys.stdout.write(formatted)
|
|
171
|
+
return 0
|
|
172
|
+
else:
|
|
173
|
+
# Directory pack into markdown and copy
|
|
174
|
+
files = find_python_files(target, DEFAULT_EXCLUDES)
|
|
175
|
+
if not files:
|
|
176
|
+
sys.stderr.write("No Python files found.\n")
|
|
177
|
+
return 1
|
|
178
|
+
items = []
|
|
179
|
+
total_orig = 0
|
|
180
|
+
total_comp = 0
|
|
181
|
+
for f in files:
|
|
182
|
+
rel = f.relative_to(target)
|
|
183
|
+
code = f.read_text(encoding="utf-8")
|
|
184
|
+
comp = compress_source(code, preserve_docstrings=not args.no_docs)
|
|
185
|
+
ot = estimate_tokens(code)
|
|
186
|
+
ct = estimate_tokens(comp)
|
|
187
|
+
total_orig += ot
|
|
188
|
+
total_comp += ct
|
|
189
|
+
items.append(FileContextItem(str(rel), code, comp, ot, ct))
|
|
190
|
+
|
|
191
|
+
bundle = format_bundle(items, output_format="md")
|
|
192
|
+
saved = max(0, total_orig - total_comp)
|
|
193
|
+
pct = (saved / total_orig * 100.0) if total_orig > 0 else 0.0
|
|
194
|
+
copy_to_clipboard(bundle)
|
|
195
|
+
sys.stderr.write(
|
|
196
|
+
f"ā Copied {len(items)} files to clipboard! "
|
|
197
|
+
f"({total_orig:,} t -> {total_comp:,} t, -{pct:.1f}% saved)\n"
|
|
198
|
+
f"Ready to paste directly into LLM prompt.\n"
|
|
199
|
+
)
|
|
200
|
+
return 0
|
|
201
|
+
|
|
202
|
+
|
|
203
|
+
def handle_inspect(args: argparse.Namespace) -> int:
|
|
204
|
+
target = Path(args.path).resolve()
|
|
205
|
+
if not target.is_file():
|
|
206
|
+
sys.stderr.write(f"Error: Target '{args.path}' must be an existing file.\n")
|
|
207
|
+
return 1
|
|
208
|
+
|
|
209
|
+
content = target.read_text(encoding="utf-8")
|
|
210
|
+
compressed = compress_source(content, preserve_docstrings=not args.no_docs)
|
|
211
|
+
report = compute_savings(content, compressed)
|
|
212
|
+
|
|
213
|
+
sys.stdout.write(f"# Compressed AST Skeleton for {target.name}\n")
|
|
214
|
+
sys.stdout.write(f"# {report.summary_line()}\n\n")
|
|
215
|
+
sys.stdout.write(compressed + "\n")
|
|
216
|
+
return 0
|
|
217
|
+
|
|
218
|
+
|
|
219
|
+
def main() -> None:
|
|
220
|
+
parser = argparse.ArgumentParser(
|
|
221
|
+
prog="codeshave",
|
|
222
|
+
description="ā” CodeShave: Zero-loss AST code context compressor for AI coding assistants.",
|
|
223
|
+
)
|
|
224
|
+
parser.add_argument("-v", "--version", action="version", version=f"codeshave {__version__}")
|
|
225
|
+
subparsers = parser.add_subparsers(dest="command", required=True)
|
|
226
|
+
|
|
227
|
+
# Pack command
|
|
228
|
+
pack_p = subparsers.add_parser("pack", help="Compress codebase directory into an LLM context bundle")
|
|
229
|
+
pack_p.add_argument("path", help="Source file or directory to compress")
|
|
230
|
+
pack_p.add_argument("-o", "--output", help="Output file path (default: stdout)")
|
|
231
|
+
pack_p.add_argument(
|
|
232
|
+
"-f",
|
|
233
|
+
"--format",
|
|
234
|
+
choices=["md", "xml", "json"],
|
|
235
|
+
default="md",
|
|
236
|
+
help="Context bundle format (default: md)",
|
|
237
|
+
)
|
|
238
|
+
pack_p.add_argument("--no-docs", action="store_true", help="Omit docstrings for maximum token savings")
|
|
239
|
+
pack_p.add_argument("--no-private", action="store_true", help="Omit private functions (_func)")
|
|
240
|
+
pack_p.add_argument("--no-sort", action="store_true", help="Disable dependency topological ordering")
|
|
241
|
+
pack_p.add_argument("--exclude", help="Comma-separated directories to exclude")
|
|
242
|
+
pack_p.add_argument("--stats", action="store_true", help="Force display of summary metrics")
|
|
243
|
+
|
|
244
|
+
# Clip command
|
|
245
|
+
clip_p = subparsers.add_parser("clip", help="Compress and copy directly to OS clipboard (ready to paste)")
|
|
246
|
+
clip_p.add_argument("path", help="Source file or directory to compress and copy")
|
|
247
|
+
clip_p.add_argument("--no-docs", action="store_true", help="Omit docstrings")
|
|
248
|
+
|
|
249
|
+
# Inspect command
|
|
250
|
+
inspect_p = subparsers.add_parser("inspect", help="Inspect compressed skeleton of a single file")
|
|
251
|
+
inspect_p.add_argument("path", help="Target Python file")
|
|
252
|
+
inspect_p.add_argument("--no-docs", action="store_true", help="Omit docstrings")
|
|
253
|
+
|
|
254
|
+
# MCP command
|
|
255
|
+
subparsers.add_parser("mcp", help="Launch Model Context Protocol (MCP) stdio server")
|
|
256
|
+
|
|
257
|
+
args = parser.parse_args()
|
|
258
|
+
|
|
259
|
+
if args.command == "pack":
|
|
260
|
+
sys.exit(handle_pack(args))
|
|
261
|
+
elif args.command == "clip":
|
|
262
|
+
sys.exit(handle_clip(args))
|
|
263
|
+
elif args.command == "inspect":
|
|
264
|
+
sys.exit(handle_inspect(args))
|
|
265
|
+
elif args.command == "mcp":
|
|
266
|
+
run_mcp_server()
|
|
267
|
+
|
|
268
|
+
|
|
269
|
+
if __name__ == "__main__":
|
|
270
|
+
main()
|
codeshave/clipboard.py
ADDED
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Zero-dependency cross-platform clipboard copy utility.
|
|
3
|
+
Works on Windows (ctypes Win32), macOS (pbcopy), and Linux (wl-copy / xclip).
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
import sys
|
|
7
|
+
import subprocess
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
def copy_to_clipboard(text: str) -> bool:
|
|
11
|
+
"""Copies text to the system clipboard without requiring third-party packages."""
|
|
12
|
+
if sys.platform == "win32":
|
|
13
|
+
try:
|
|
14
|
+
import ctypes
|
|
15
|
+
from ctypes import wintypes
|
|
16
|
+
|
|
17
|
+
user32 = ctypes.windll.user32
|
|
18
|
+
kernel32 = ctypes.windll.kernel32
|
|
19
|
+
|
|
20
|
+
GMEM_MOVEABLE = 0x0002
|
|
21
|
+
CF_UNICODETEXT = 13
|
|
22
|
+
|
|
23
|
+
user32.OpenClipboard.argtypes = [wintypes.HWND]
|
|
24
|
+
user32.OpenClipboard.restype = wintypes.BOOL
|
|
25
|
+
user32.CloseClipboard.argtypes = []
|
|
26
|
+
user32.CloseClipboard.restype = wintypes.BOOL
|
|
27
|
+
user32.EmptyClipboard.argtypes = []
|
|
28
|
+
user32.EmptyClipboard.restype = wintypes.BOOL
|
|
29
|
+
user32.SetClipboardData.argtypes = [wintypes.UINT, wintypes.HANDLE]
|
|
30
|
+
user32.SetClipboardData.restype = wintypes.HANDLE
|
|
31
|
+
|
|
32
|
+
kernel32.GlobalAlloc.argtypes = [wintypes.UINT, ctypes.c_size_t]
|
|
33
|
+
kernel32.GlobalAlloc.restype = wintypes.HGLOBAL
|
|
34
|
+
kernel32.GlobalLock.argtypes = [wintypes.HGLOBAL]
|
|
35
|
+
kernel32.GlobalLock.restype = ctypes.c_void_p
|
|
36
|
+
kernel32.GlobalUnlock.argtypes = [wintypes.HGLOBAL]
|
|
37
|
+
kernel32.GlobalUnlock.restype = wintypes.BOOL
|
|
38
|
+
|
|
39
|
+
encoded = text.encode("utf-16le") + b"\x00\x00"
|
|
40
|
+
h_mem = kernel32.GlobalAlloc(GMEM_MOVEABLE, len(encoded))
|
|
41
|
+
if not h_mem:
|
|
42
|
+
return False
|
|
43
|
+
|
|
44
|
+
ptr = kernel32.GlobalLock(h_mem)
|
|
45
|
+
if not ptr:
|
|
46
|
+
return False
|
|
47
|
+
|
|
48
|
+
ctypes.memmove(ptr, encoded, len(encoded))
|
|
49
|
+
kernel32.GlobalUnlock(h_mem)
|
|
50
|
+
|
|
51
|
+
if not user32.OpenClipboard(None):
|
|
52
|
+
return False
|
|
53
|
+
|
|
54
|
+
user32.EmptyClipboard()
|
|
55
|
+
user32.SetClipboardData(CF_UNICODETEXT, h_mem)
|
|
56
|
+
user32.CloseClipboard()
|
|
57
|
+
return True
|
|
58
|
+
except Exception:
|
|
59
|
+
pass
|
|
60
|
+
|
|
61
|
+
# Fallback to standard CLI utilities
|
|
62
|
+
commands = []
|
|
63
|
+
if sys.platform == "darwin":
|
|
64
|
+
commands = [["pbcopy"]]
|
|
65
|
+
else:
|
|
66
|
+
commands = [["wl-copy"], ["xclip", "-selection", "clipboard"], ["xsel", "--clipboard", "--input"]]
|
|
67
|
+
|
|
68
|
+
for cmd in commands:
|
|
69
|
+
try:
|
|
70
|
+
proc = subprocess.Popen(cmd, stdin=subprocess.PIPE, close_fds=True)
|
|
71
|
+
proc.communicate(input=text.encode("utf-8"))
|
|
72
|
+
if proc.returncode == 0:
|
|
73
|
+
return True
|
|
74
|
+
except Exception:
|
|
75
|
+
continue
|
|
76
|
+
|
|
77
|
+
return False
|
codeshave/estimator.py
ADDED
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Token estimation and savings calculation metrics.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
from __future__ import annotations
|
|
6
|
+
|
|
7
|
+
from dataclasses import dataclass
|
|
8
|
+
from typing import Optional
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
@dataclass
|
|
12
|
+
class SavingsReport:
|
|
13
|
+
original_chars: int
|
|
14
|
+
compressed_chars: int
|
|
15
|
+
original_tokens: int
|
|
16
|
+
compressed_tokens: int
|
|
17
|
+
tokens_saved: int
|
|
18
|
+
reduction_percentage: float
|
|
19
|
+
estimated_cost_saved_usd: float # Based on typical $3.00 / 1M prompt tokens
|
|
20
|
+
|
|
21
|
+
def summary_line(self) -> str:
|
|
22
|
+
return (
|
|
23
|
+
f"Original: {self.original_tokens:,} t -> "
|
|
24
|
+
f"Skeleton: {self.compressed_tokens:,} t | "
|
|
25
|
+
f"Saved: {self.tokens_saved:,} t ({self.reduction_percentage:.1f}%)"
|
|
26
|
+
)
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def estimate_tokens(text: str) -> int:
|
|
30
|
+
"""
|
|
31
|
+
Estimates token count with high accuracy without requiring heavy external binaries.
|
|
32
|
+
Uses standard BPE heuristic: ~3.7 characters per token for source code.
|
|
33
|
+
If tiktoken is installed in the user's environment, it falls back to exact encoding.
|
|
34
|
+
"""
|
|
35
|
+
if not text:
|
|
36
|
+
return 0
|
|
37
|
+
|
|
38
|
+
try:
|
|
39
|
+
import tiktoken
|
|
40
|
+
enc = tiktoken.get_encoding("cl100k_base")
|
|
41
|
+
return len(enc.encode(text, disallowed_special=()))
|
|
42
|
+
except (ImportError, Exception):
|
|
43
|
+
# Precise code token heuristic calibrated across Python AST benchmarks
|
|
44
|
+
return max(1, int(len(text) / 3.7))
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def compute_savings(original_text: str, compressed_text: str) -> SavingsReport:
|
|
48
|
+
"""
|
|
49
|
+
Computes comparative metrics between original and compressed representations.
|
|
50
|
+
"""
|
|
51
|
+
orig_chars = len(original_text)
|
|
52
|
+
comp_chars = len(compressed_text)
|
|
53
|
+
orig_tokens = estimate_tokens(original_text)
|
|
54
|
+
comp_tokens = estimate_tokens(compressed_text)
|
|
55
|
+
|
|
56
|
+
saved_tokens = max(0, orig_tokens - comp_tokens)
|
|
57
|
+
pct = (saved_tokens / orig_tokens * 100.0) if orig_tokens > 0 else 0.0
|
|
58
|
+
cost_saved = (saved_tokens / 1_000_000.0) * 3.00 # $3 / 1M tokens
|
|
59
|
+
|
|
60
|
+
return SavingsReport(
|
|
61
|
+
original_chars=orig_chars,
|
|
62
|
+
compressed_chars=comp_chars,
|
|
63
|
+
original_tokens=orig_tokens,
|
|
64
|
+
compressed_tokens=comp_tokens,
|
|
65
|
+
tokens_saved=saved_tokens,
|
|
66
|
+
reduction_percentage=pct,
|
|
67
|
+
estimated_cost_saved_usd=cost_saved,
|
|
68
|
+
)
|
codeshave/formatters.py
ADDED
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Bundle formatters for LLM prompt ingestion (Markdown, XML, JSON).
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
from __future__ import annotations
|
|
6
|
+
|
|
7
|
+
import json
|
|
8
|
+
from dataclasses import dataclass
|
|
9
|
+
from pathlib import Path
|
|
10
|
+
from typing import List
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
@dataclass
|
|
14
|
+
class FileContextItem:
|
|
15
|
+
relative_path: str
|
|
16
|
+
original_code: str
|
|
17
|
+
compressed_code: str
|
|
18
|
+
original_tokens: int
|
|
19
|
+
compressed_tokens: int
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def format_markdown(items: List[FileContextItem]) -> str:
|
|
23
|
+
"""Formats bundled files into clean GitHub-flavored markdown."""
|
|
24
|
+
blocks: List[str] = [
|
|
25
|
+
"# Codebase Context Bundle",
|
|
26
|
+
"> Generated by CodeShave (https://github.com/jaideepkrishna2008-ui/codeshave)",
|
|
27
|
+
"",
|
|
28
|
+
]
|
|
29
|
+
|
|
30
|
+
for item in items:
|
|
31
|
+
pct = (
|
|
32
|
+
(1.0 - (item.compressed_tokens / item.original_tokens)) * 100.0
|
|
33
|
+
if item.original_tokens > 0
|
|
34
|
+
else 0.0
|
|
35
|
+
)
|
|
36
|
+
blocks.append(
|
|
37
|
+
f"### File: `{item.relative_path}` "
|
|
38
|
+
f"*(Tokens: {item.compressed_tokens:,} | -{pct:.1f}% reduction)*"
|
|
39
|
+
)
|
|
40
|
+
blocks.append(f"```python\n{item.compressed_code}\n```\n")
|
|
41
|
+
|
|
42
|
+
return "\n".join(blocks)
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def format_xml(items: List[FileContextItem]) -> str:
|
|
46
|
+
"""
|
|
47
|
+
Formats bundled files into Claude / Anthropic standard XML document tagging,
|
|
48
|
+
which optimizes prompt recall in multi-turn dialogues.
|
|
49
|
+
"""
|
|
50
|
+
lines: List[str] = ["<documents>"]
|
|
51
|
+
for idx, item in enumerate(items, 1):
|
|
52
|
+
lines.append(f' <document index="{idx}">')
|
|
53
|
+
lines.append(f" <source>{item.relative_path}</source>")
|
|
54
|
+
lines.append(" <document_content>")
|
|
55
|
+
lines.append(item.compressed_code)
|
|
56
|
+
lines.append(" </document_content>")
|
|
57
|
+
lines.append(" </document>")
|
|
58
|
+
lines.append("</documents>")
|
|
59
|
+
return "\n".join(lines)
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
def format_json(items: List[FileContextItem]) -> str:
|
|
63
|
+
"""Formats bundled items as JSON for programmatic agent ingestion."""
|
|
64
|
+
data = [
|
|
65
|
+
{
|
|
66
|
+
"path": item.relative_path,
|
|
67
|
+
"content": item.compressed_code,
|
|
68
|
+
"metrics": {
|
|
69
|
+
"original_tokens": item.original_tokens,
|
|
70
|
+
"compressed_tokens": item.compressed_tokens,
|
|
71
|
+
"saved_tokens": max(0, item.original_tokens - item.compressed_tokens),
|
|
72
|
+
},
|
|
73
|
+
}
|
|
74
|
+
for item in items
|
|
75
|
+
]
|
|
76
|
+
return json.dumps({"codeshave_version": "0.1.0", "files": data}, indent=2)
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def format_bundle(items: List[FileContextItem], output_format: str = "markdown") -> str:
|
|
80
|
+
fmt = output_format.lower().strip()
|
|
81
|
+
if fmt == "xml":
|
|
82
|
+
return format_xml(items)
|
|
83
|
+
elif fmt == "json":
|
|
84
|
+
return format_json(items)
|
|
85
|
+
return format_markdown(items)
|
codeshave/graph.py
ADDED
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Dependency graph and topological file ordering.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
from __future__ import annotations
|
|
6
|
+
|
|
7
|
+
import ast
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
from typing import Dict, List, Set
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class DependencyResolver:
|
|
13
|
+
"""
|
|
14
|
+
Parses import dependencies across a collection of files and sorts them
|
|
15
|
+
so base interfaces and models precede dependent consumers.
|
|
16
|
+
"""
|
|
17
|
+
|
|
18
|
+
def __init__(self, root_dir: Path):
|
|
19
|
+
self.root_dir = root_dir.resolve()
|
|
20
|
+
|
|
21
|
+
def extract_local_imports(self, filepath: Path) -> Set[str]:
|
|
22
|
+
"""Extracts locally resolved module import names from a Python file."""
|
|
23
|
+
imports: Set[str] = set()
|
|
24
|
+
try:
|
|
25
|
+
tree = ast.parse(filepath.read_text(encoding="utf-8"))
|
|
26
|
+
except Exception:
|
|
27
|
+
return imports
|
|
28
|
+
|
|
29
|
+
for node in ast.walk(tree):
|
|
30
|
+
if isinstance(node, ast.Import):
|
|
31
|
+
for alias in node.names:
|
|
32
|
+
imports.add(alias.name.split(".")[0])
|
|
33
|
+
elif isinstance(node, ast.ImportFrom):
|
|
34
|
+
if node.module:
|
|
35
|
+
imports.add(node.module.split(".")[0])
|
|
36
|
+
|
|
37
|
+
return imports
|
|
38
|
+
|
|
39
|
+
def sort_files_by_dependency(self, filepaths: List[Path]) -> List[Path]:
|
|
40
|
+
"""
|
|
41
|
+
Orders files topologically. Foundational files (like models, schemas, utils)
|
|
42
|
+
are placed first, providing better priming context for LLM understanding.
|
|
43
|
+
"""
|
|
44
|
+
graph: Dict[Path, Set[Path]] = {f: set() for f in filepaths}
|
|
45
|
+
module_to_path: Dict[str, Path] = {
|
|
46
|
+
f.stem: f for f in filepaths
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
for path in filepaths:
|
|
50
|
+
imported_names = self.extract_local_imports(path)
|
|
51
|
+
for name in imported_names:
|
|
52
|
+
if name in module_to_path and module_to_path[name] != path:
|
|
53
|
+
graph[path].add(module_to_path[name])
|
|
54
|
+
|
|
55
|
+
# Topological sort (Kahn's algorithm / DFS)
|
|
56
|
+
visited: Set[Path] = set()
|
|
57
|
+
visiting: Set[Path] = set()
|
|
58
|
+
ordered: List[Path] = []
|
|
59
|
+
|
|
60
|
+
def dfs(node: Path):
|
|
61
|
+
if node in visiting:
|
|
62
|
+
return # Cycle detected; break gracefully
|
|
63
|
+
if node not in visited:
|
|
64
|
+
visiting.add(node)
|
|
65
|
+
for dep in graph.get(node, []):
|
|
66
|
+
dfs(dep)
|
|
67
|
+
visiting.remove(node)
|
|
68
|
+
visited.add(node)
|
|
69
|
+
ordered.append(node)
|
|
70
|
+
|
|
71
|
+
for p in filepaths:
|
|
72
|
+
if p not in visited:
|
|
73
|
+
dfs(p)
|
|
74
|
+
|
|
75
|
+
return ordered
|
codeshave/mcp.py
ADDED
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Standard Model Context Protocol (MCP) server for CodeShave.
|
|
3
|
+
Runs over standard I/O (stdio) and integrates with Claude Desktop, Cursor, and Windsurf.
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
import json
|
|
7
|
+
import sys
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
from typing import Any, Dict
|
|
10
|
+
|
|
11
|
+
from codeshave import __version__
|
|
12
|
+
from codeshave.estimator import compute_savings
|
|
13
|
+
from codeshave.parser import compress_source
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def create_tool_definitions() -> list[Dict[str, Any]]:
|
|
17
|
+
return [
|
|
18
|
+
{
|
|
19
|
+
"name": "shave_code",
|
|
20
|
+
"description": "Compress raw Python source code into a syntax-valid AST skeleton for prompts.",
|
|
21
|
+
"inputSchema": {
|
|
22
|
+
"type": "object",
|
|
23
|
+
"properties": {
|
|
24
|
+
"source_code": {
|
|
25
|
+
"type": "string",
|
|
26
|
+
"description": "Raw Python code to compress",
|
|
27
|
+
},
|
|
28
|
+
"preserve_docstrings": {
|
|
29
|
+
"type": "boolean",
|
|
30
|
+
"default": True,
|
|
31
|
+
"description": "Whether to preserve function and class docstrings",
|
|
32
|
+
},
|
|
33
|
+
},
|
|
34
|
+
"required": ["source_code"],
|
|
35
|
+
},
|
|
36
|
+
},
|
|
37
|
+
{
|
|
38
|
+
"name": "shave_file",
|
|
39
|
+
"description": "Read a file from disk and return its compressed AST skeleton.",
|
|
40
|
+
"inputSchema": {
|
|
41
|
+
"type": "object",
|
|
42
|
+
"properties": {
|
|
43
|
+
"file_path": {
|
|
44
|
+
"type": "string",
|
|
45
|
+
"description": "Absolute or relative path to the Python file",
|
|
46
|
+
},
|
|
47
|
+
"preserve_docstrings": {
|
|
48
|
+
"type": "boolean",
|
|
49
|
+
"default": True,
|
|
50
|
+
},
|
|
51
|
+
},
|
|
52
|
+
"required": ["file_path"],
|
|
53
|
+
},
|
|
54
|
+
},
|
|
55
|
+
]
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
def handle_call_tool(params: Dict[str, Any]) -> Dict[str, Any]:
|
|
59
|
+
name = params.get("name")
|
|
60
|
+
args = params.get("arguments", {})
|
|
61
|
+
|
|
62
|
+
if name == "shave_code":
|
|
63
|
+
code = args.get("source_code", "")
|
|
64
|
+
preserve_docs = args.get("preserve_docstrings", True)
|
|
65
|
+
skeleton = compress_source(code, preserve_docstrings=preserve_docs)
|
|
66
|
+
report = compute_savings(code, skeleton)
|
|
67
|
+
text = (
|
|
68
|
+
f"# Compressed by CodeShave ({report.summary_line()})\n\n"
|
|
69
|
+
f"```python\n{skeleton}\n```"
|
|
70
|
+
)
|
|
71
|
+
return {
|
|
72
|
+
"content": [{"type": "text", "text": text}],
|
|
73
|
+
"isError": False,
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
elif name == "shave_file":
|
|
77
|
+
p = Path(args.get("file_path", ""))
|
|
78
|
+
if not p.is_file():
|
|
79
|
+
return {
|
|
80
|
+
"content": [{"type": "text", "text": f"Error: File '{p}' does not exist."}],
|
|
81
|
+
"isError": True,
|
|
82
|
+
}
|
|
83
|
+
code = p.read_text(encoding="utf-8")
|
|
84
|
+
preserve_docs = args.get("preserve_docstrings", True)
|
|
85
|
+
skeleton = compress_source(code, preserve_docstrings=preserve_docs)
|
|
86
|
+
report = compute_savings(code, skeleton)
|
|
87
|
+
text = (
|
|
88
|
+
f"# File: {p.name} ({report.summary_line()})\n\n"
|
|
89
|
+
f"```python\n{skeleton}\n```"
|
|
90
|
+
)
|
|
91
|
+
return {
|
|
92
|
+
"content": [{"type": "text", "text": text}],
|
|
93
|
+
"isError": False,
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
return {
|
|
97
|
+
"content": [{"type": "text", "text": f"Unknown tool: {name}"}],
|
|
98
|
+
"isError": True,
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
def run_mcp_server() -> None:
|
|
103
|
+
"""Standard stdio JSON-RPC 2.0 loop."""
|
|
104
|
+
sys.stderr.write(f"ā” CodeShave MCP Server v{__version__} listening on stdio...\n")
|
|
105
|
+
while True:
|
|
106
|
+
line = sys.stdin.readline()
|
|
107
|
+
if not line:
|
|
108
|
+
break
|
|
109
|
+
line = line.strip()
|
|
110
|
+
if not line:
|
|
111
|
+
continue
|
|
112
|
+
|
|
113
|
+
try:
|
|
114
|
+
req = json.loads(line)
|
|
115
|
+
except Exception:
|
|
116
|
+
continue
|
|
117
|
+
|
|
118
|
+
req_id = req.get("id")
|
|
119
|
+
method = req.get("method")
|
|
120
|
+
params = req.get("params", {})
|
|
121
|
+
|
|
122
|
+
if method == "initialize":
|
|
123
|
+
resp = {
|
|
124
|
+
"jsonrpc": "2.0",
|
|
125
|
+
"id": req_id,
|
|
126
|
+
"result": {
|
|
127
|
+
"protocolVersion": "2024-11-05",
|
|
128
|
+
"capabilities": {"tools": {}},
|
|
129
|
+
"serverInfo": {"name": "codeshave", "version": __version__},
|
|
130
|
+
},
|
|
131
|
+
}
|
|
132
|
+
elif method == "tools/list":
|
|
133
|
+
resp = {
|
|
134
|
+
"jsonrpc": "2.0",
|
|
135
|
+
"id": req_id,
|
|
136
|
+
"result": {"tools": create_tool_definitions()},
|
|
137
|
+
}
|
|
138
|
+
elif method == "tools/call":
|
|
139
|
+
result = handle_call_tool(params)
|
|
140
|
+
resp = {
|
|
141
|
+
"jsonrpc": "2.0",
|
|
142
|
+
"id": req_id,
|
|
143
|
+
"result": result,
|
|
144
|
+
}
|
|
145
|
+
else:
|
|
146
|
+
resp = {
|
|
147
|
+
"jsonrpc": "2.0",
|
|
148
|
+
"id": req_id,
|
|
149
|
+
"error": {"code": -32601, "message": "Method not found"},
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
sys.stdout.write(json.dumps(resp) + "\n")
|
|
153
|
+
sys.stdout.flush()
|
codeshave/parser.py
ADDED
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
"""
|
|
2
|
+
AST-based code compression and skeleton extraction.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
from __future__ import annotations
|
|
6
|
+
|
|
7
|
+
import ast
|
|
8
|
+
from dataclasses import dataclass, field
|
|
9
|
+
from typing import Optional, Set
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
@dataclass
|
|
13
|
+
class SymbolInfo:
|
|
14
|
+
name: str
|
|
15
|
+
kind: str # 'class', 'function', 'async_function', 'variable'
|
|
16
|
+
line_number: int
|
|
17
|
+
docstring: Optional[str] = None
|
|
18
|
+
parameters: list[str] = field(default_factory=list)
|
|
19
|
+
return_type: Optional[str] = None
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
class SkeletonTransformer(ast.NodeTransformer):
|
|
23
|
+
"""
|
|
24
|
+
Transforms a Python Abstract Syntax Tree (AST) into a structural skeleton.
|
|
25
|
+
Strips executable implementation bodies while preserving:
|
|
26
|
+
- Function/method signatures, parameter type annotations, and default values
|
|
27
|
+
- Return type annotations
|
|
28
|
+
- Decorators
|
|
29
|
+
- Class hierarchies, base classes, and class-level type annotations
|
|
30
|
+
- Module-level constants, type aliases, and public exports (__all__)
|
|
31
|
+
- Docstrings (optional)
|
|
32
|
+
"""
|
|
33
|
+
|
|
34
|
+
def __init__(self, preserve_docstrings: bool = True, preserve_private: bool = True):
|
|
35
|
+
self.preserve_docstrings = preserve_docstrings
|
|
36
|
+
self.preserve_private = preserve_private
|
|
37
|
+
|
|
38
|
+
def _create_ellipsis_body(self, docstring: Optional[str]) -> list[ast.stmt]:
|
|
39
|
+
body: list[ast.stmt] = []
|
|
40
|
+
if self.preserve_docstrings and docstring:
|
|
41
|
+
body.append(ast.Expr(value=ast.Constant(value=docstring)))
|
|
42
|
+
body.append(ast.Expr(value=ast.Constant(value=Ellipsis)))
|
|
43
|
+
return body
|
|
44
|
+
|
|
45
|
+
def visit_FunctionDef(self, node: ast.FunctionDef) -> Optional[ast.FunctionDef]:
|
|
46
|
+
if not self.preserve_private and node.name.startswith("_") and not node.name.startswith("__"):
|
|
47
|
+
return None
|
|
48
|
+
docstring = ast.get_docstring(node)
|
|
49
|
+
node.body = self._create_ellipsis_body(docstring)
|
|
50
|
+
return node
|
|
51
|
+
|
|
52
|
+
def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> Optional[ast.AsyncFunctionDef]:
|
|
53
|
+
if not self.preserve_private and node.name.startswith("_") and not node.name.startswith("__"):
|
|
54
|
+
return None
|
|
55
|
+
docstring = ast.get_docstring(node)
|
|
56
|
+
node.body = self._create_ellipsis_body(docstring)
|
|
57
|
+
return node
|
|
58
|
+
|
|
59
|
+
def visit_ClassDef(self, node: ast.ClassDef) -> Optional[ast.ClassDef]:
|
|
60
|
+
if not self.preserve_private and node.name.startswith("_") and not node.name.startswith("__"):
|
|
61
|
+
return None
|
|
62
|
+
|
|
63
|
+
docstring = ast.get_docstring(node)
|
|
64
|
+
new_body: list[ast.stmt] = []
|
|
65
|
+
if self.preserve_docstrings and docstring:
|
|
66
|
+
new_body.append(ast.Expr(value=ast.Constant(value=docstring)))
|
|
67
|
+
|
|
68
|
+
for child in node.body:
|
|
69
|
+
if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)):
|
|
70
|
+
transformed = self.visit(child)
|
|
71
|
+
if transformed:
|
|
72
|
+
new_body.append(transformed)
|
|
73
|
+
elif isinstance(child, ast.ClassDef):
|
|
74
|
+
transformed = self.visit(child)
|
|
75
|
+
if transformed:
|
|
76
|
+
new_body.append(transformed)
|
|
77
|
+
elif isinstance(child, (ast.AnnAssign, ast.Assign)):
|
|
78
|
+
# Keep class-level type definitions and constants
|
|
79
|
+
new_body.append(child)
|
|
80
|
+
|
|
81
|
+
if not new_body:
|
|
82
|
+
new_body.append(ast.Expr(value=ast.Constant(value=Ellipsis)))
|
|
83
|
+
|
|
84
|
+
node.body = new_body
|
|
85
|
+
return node
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
class ModuleSkeletonFilter(ast.NodeTransformer):
|
|
89
|
+
"""
|
|
90
|
+
Cleans top-level statements to retain only definitions, exports, and imports.
|
|
91
|
+
"""
|
|
92
|
+
|
|
93
|
+
def __init__(self, transformer: SkeletonTransformer):
|
|
94
|
+
self.transformer = transformer
|
|
95
|
+
|
|
96
|
+
def visit_Module(self, node: ast.Module) -> ast.Module:
|
|
97
|
+
new_body: list[ast.stmt] = []
|
|
98
|
+
module_doc = ast.get_docstring(node)
|
|
99
|
+
if self.transformer.preserve_docstrings and module_doc:
|
|
100
|
+
new_body.append(ast.Expr(value=ast.Constant(value=module_doc)))
|
|
101
|
+
|
|
102
|
+
for stmt in node.body:
|
|
103
|
+
if isinstance(stmt, (ast.Import, ast.ImportFrom)):
|
|
104
|
+
new_body.append(stmt)
|
|
105
|
+
elif isinstance(stmt, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
|
|
106
|
+
transformed = self.transformer.visit(stmt)
|
|
107
|
+
if transformed:
|
|
108
|
+
new_body.append(transformed)
|
|
109
|
+
elif isinstance(stmt, ast.AnnAssign):
|
|
110
|
+
# Type annotations (e.g. x: int = 1 or my_type: TypeAlias)
|
|
111
|
+
new_body.append(stmt)
|
|
112
|
+
elif isinstance(stmt, ast.Assign):
|
|
113
|
+
# Check for __all__ or UPPERCASE_CONSTANTS
|
|
114
|
+
is_constant_or_export = False
|
|
115
|
+
for target in stmt.targets:
|
|
116
|
+
if isinstance(target, ast.Name):
|
|
117
|
+
if target.id == "__all__" or target.id.isupper():
|
|
118
|
+
is_constant_or_export = True
|
|
119
|
+
break
|
|
120
|
+
if is_constant_or_export:
|
|
121
|
+
new_body.append(stmt)
|
|
122
|
+
|
|
123
|
+
node.body = new_body
|
|
124
|
+
return node
|
|
125
|
+
|
|
126
|
+
|
|
127
|
+
def compress_source(
|
|
128
|
+
source_code: str,
|
|
129
|
+
preserve_docstrings: bool = True,
|
|
130
|
+
preserve_private: bool = True,
|
|
131
|
+
) -> str:
|
|
132
|
+
"""
|
|
133
|
+
Parses raw source code into an AST and returns a syntactically valid,
|
|
134
|
+
cleanly unparsed structural skeleton.
|
|
135
|
+
"""
|
|
136
|
+
tree = ast.parse(source_code)
|
|
137
|
+
transformer = SkeletonTransformer(
|
|
138
|
+
preserve_docstrings=preserve_docstrings,
|
|
139
|
+
preserve_private=preserve_private,
|
|
140
|
+
)
|
|
141
|
+
module_filter = ModuleSkeletonFilter(transformer)
|
|
142
|
+
compressed_tree = module_filter.visit(tree)
|
|
143
|
+
ast.fix_missing_locations(compressed_tree)
|
|
144
|
+
return ast.unparse(compressed_tree)
|
|
145
|
+
|
|
146
|
+
|
|
147
|
+
def extract_symbols(source_code: str) -> list[SymbolInfo]:
|
|
148
|
+
"""
|
|
149
|
+
Extracts all classes, functions, and top-level definitions with metadata.
|
|
150
|
+
"""
|
|
151
|
+
tree = ast.parse(source_code)
|
|
152
|
+
symbols: list[SymbolInfo] = []
|
|
153
|
+
|
|
154
|
+
for node in tree.body:
|
|
155
|
+
if isinstance(node, ast.ClassDef):
|
|
156
|
+
symbols.append(
|
|
157
|
+
SymbolInfo(
|
|
158
|
+
name=node.name,
|
|
159
|
+
kind="class",
|
|
160
|
+
line_number=node.lineno,
|
|
161
|
+
docstring=ast.get_docstring(node),
|
|
162
|
+
)
|
|
163
|
+
)
|
|
164
|
+
elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
|
|
165
|
+
kind = "async_function" if isinstance(node, ast.AsyncFunctionDef) else "function"
|
|
166
|
+
params = [arg.arg for arg in node.args.args]
|
|
167
|
+
ret_type = ast.unparse(node.returns) if node.returns else None
|
|
168
|
+
symbols.append(
|
|
169
|
+
SymbolInfo(
|
|
170
|
+
name=node.name,
|
|
171
|
+
kind=kind,
|
|
172
|
+
line_number=node.lineno,
|
|
173
|
+
docstring=ast.get_docstring(node),
|
|
174
|
+
parameters=params,
|
|
175
|
+
return_type=ret_type,
|
|
176
|
+
)
|
|
177
|
+
)
|
|
178
|
+
|
|
179
|
+
return symbols
|
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: codeshave
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Deterministic AST code context compressor for AI coding assistants and local models
|
|
5
|
+
Author-email: Jaideep Krishna A <jaideepkrishna2008@gmail.com>
|
|
6
|
+
Requires-Python: >=3.10
|
|
7
|
+
Description-Content-Type: text/markdown
|
|
8
|
+
|
|
9
|
+
# CodeShave
|
|
10
|
+
|
|
11
|
+
<p align="center">
|
|
12
|
+
<img src="assets/banner.svg" alt="CodeShave Banner" width="100%">
|
|
13
|
+
</p>
|
|
14
|
+
|
|
15
|
+
<p align="center">
|
|
16
|
+
<b>High-speed, deterministic AST code context compressor for AI coding assistants and local LLMs.</b><br>
|
|
17
|
+
Reduces prompt tokens by 60% to 80% while preserving valid syntax, type signatures, and class hierarchies.
|
|
18
|
+
</p>
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## ā” Terminal Demo
|
|
23
|
+
|
|
24
|
+
<p align="center">
|
|
25
|
+
<img src="assets/demo.svg" alt="CodeShave CLI Demonstration" width="100%">
|
|
26
|
+
</p>
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## šÆ Why CodeShave?
|
|
31
|
+
|
|
32
|
+
When developers feed large directories to LLMs or AI agents, context windows quickly fill up, latency spikes, and API token bills mount.
|
|
33
|
+
|
|
34
|
+
Traditional approaches either:
|
|
35
|
+
1. Truncate files blindly, breaking syntax trees and references.
|
|
36
|
+
2. Rely on costly, slow LLMs to summarize code before prompting.
|
|
37
|
+
|
|
38
|
+
**CodeShave** uses Python's native Abstract Syntax Tree (AST) engine to deterministically transform code into clean interface skeletons:
|
|
39
|
+
- Strips implementation logic inside functions and replaces with `...`.
|
|
40
|
+
- Preserves all class structures, inheritance, and attributes.
|
|
41
|
+
- Retains parameter type annotations, defaults, and return types.
|
|
42
|
+
- Maintains decorators, docstrings, and module-level exports.
|
|
43
|
+
- Formats context blocks into Markdown, Claude-optimized XML, or JSON.
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## šļø Architecture
|
|
48
|
+
|
|
49
|
+
<p align="center">
|
|
50
|
+
<img src="assets/architecture.svg" alt="CodeShave Architecture Diagram" width="100%">
|
|
51
|
+
</p>
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
## š Quickstart
|
|
56
|
+
|
|
57
|
+
### Installation
|
|
58
|
+
|
|
59
|
+
Install directly via `pip` from GitHub:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
pip install git+https://github.com/jaideepkrishna2008-ui/codeshave.git
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Or clone for local development:
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
git clone https://github.com/jaideepkrishna2008-ui/codeshave.git
|
|
69
|
+
cd codeshave
|
|
70
|
+
pip install -e .
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### ā” CLI Commands
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
# š One-Click Clipboard Copy: Compress and copy directly to clipboard
|
|
77
|
+
codeshave clip ./src
|
|
78
|
+
codeshave clip ./src/models.py
|
|
79
|
+
# -> Copied to clipboard! Ready to paste directly into ChatGPT, Claude, or Cursor!
|
|
80
|
+
|
|
81
|
+
# š¦ Pack directory into an LLM context bundle
|
|
82
|
+
codeshave pack ./src -o llm_context.md
|
|
83
|
+
|
|
84
|
+
# š·ļø Generate Claude-optimized XML bundle with live savings statistics
|
|
85
|
+
codeshave pack ./src --format xml --stats -o llm_context.xml
|
|
86
|
+
|
|
87
|
+
# š Inspect a single file's compressed skeleton
|
|
88
|
+
codeshave inspect ./src/services/billing.py
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
---
|
|
92
|
+
|
|
93
|
+
## š Model Context Protocol (MCP) Integration
|
|
94
|
+
|
|
95
|
+
CodeShave runs as a turnkey **MCP Server** over standard I/O, allowing **Claude Desktop**, **Cursor**, and **Windsurf** to automatically compress files on the fly before reasoning:
|
|
96
|
+
|
|
97
|
+
Add to your `claude_desktop_config.json`:
|
|
98
|
+
|
|
99
|
+
```json
|
|
100
|
+
{
|
|
101
|
+
"mcpServers": {
|
|
102
|
+
"codeshave": {
|
|
103
|
+
"command": "codeshave",
|
|
104
|
+
"args": ["mcp"]
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
### Python API
|
|
111
|
+
|
|
112
|
+
```python
|
|
113
|
+
from codeshave import compress_source, compute_savings
|
|
114
|
+
|
|
115
|
+
raw_code = open("service.py").read()
|
|
116
|
+
skeleton = compress_source(raw_code, preserve_docstrings=True)
|
|
117
|
+
report = compute_savings(raw_code, skeleton)
|
|
118
|
+
|
|
119
|
+
print(skeleton)
|
|
120
|
+
print(report.summary_line())
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
## š Token Savings Benchmark
|
|
126
|
+
|
|
127
|
+
| Source Type | Original Tokens | CodeShave Skeleton | Reduction | Syntax Status |
|
|
128
|
+
| :--- | :--- | :--- | :--- | :--- |
|
|
129
|
+
| Data Models | 3,460 t | 920 t | **73.4%** | ā
Valid AST |
|
|
130
|
+
| API Endpoints | 4,210 t | 780 t | **81.5%** | ā
Valid AST |
|
|
131
|
+
| Business Logic | 6,840 t | 1,120 t | **83.6%** | ā
Valid AST |
|
|
132
|
+
| Utility Scripts | 1,000 t | 400 t | **60.0%** | ā
Valid AST |
|
|
133
|
+
|
|
134
|
+
---
|
|
135
|
+
|
|
136
|
+
## š Sponsorship & Backing
|
|
137
|
+
|
|
138
|
+
If CodeShave saves you tokens, reduces your API bills, or accelerates your agent workflow, consider supporting ongoing open-source development:
|
|
139
|
+
|
|
140
|
+
<p align="left">
|
|
141
|
+
<a href="https://buymeacoffee.com/jaideep.360" target="_blank">
|
|
142
|
+
<img src="https://img.shields.io/badge/Buy%20Me%20A%20Coffee-jaideep.360-orange?style=for-the-badge&logo=buy-me-a-coffee" alt="Buy Me A Coffee" />
|
|
143
|
+
</a>
|
|
144
|
+
|
|
145
|
+
<a href="https://github.com/sponsors/jaideepkrishna2008-ui" target="_blank">
|
|
146
|
+
<img src="https://img.shields.io/badge/Sponsor%20on%20GitHub-jaideepkrishna2008--ui-ea4aaa?style=for-the-badge&logo=github-sponsors" alt="Sponsor on GitHub" />
|
|
147
|
+
</a>
|
|
148
|
+
</p>
|
|
149
|
+
|
|
150
|
+
* **Buy Me A Coffee**: [https://buymeacoffee.com/jaideep.360](https://buymeacoffee.com/jaideep.360)
|
|
151
|
+
* **GitHub Sponsors**: [https://github.com/sponsors/jaideepkrishna2008-ui](https://github.com/sponsors/jaideepkrishna2008-ui)
|
|
152
|
+
|
|
153
|
+
---
|
|
154
|
+
|
|
155
|
+
## š License
|
|
156
|
+
|
|
157
|
+
Created by **Jaideep Krishna A** ([@jaideepkrishna2008-ui](https://github.com/jaideepkrishna2008-ui)).
|
|
158
|
+
Licensed under the Apache License 2.0 or MIT equivalent open-source terms.
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
codeshave/__init__.py,sha256=UGpMQTFcI2qLQnnWCy5VTvF2dinWF95UlqBXrGacPqk,689
|
|
2
|
+
codeshave/__main__.py,sha256=_Wb5Bk32Owyy_K-T0qihC5dRUqp4GdFYJdidFC9_wIo,123
|
|
3
|
+
codeshave/cli.py,sha256=SR2Cf3b_dwA_wtJLdgsIxh7fGMC0dz7JzdVBbP90Now,9845
|
|
4
|
+
codeshave/clipboard.py,sha256=ycmpcjOssFdw7cMyHUN9L2huVb7boNIYKS1ZwiTPav0,2627
|
|
5
|
+
codeshave/estimator.py,sha256=fwJHZ6I3G0WJhumDHS-d6xMx5vF2RoV-ak8HjeGqS2w,2183
|
|
6
|
+
codeshave/formatters.py,sha256=On1TFv5OCRd9UFIJxLWBAJGjBijgMVqwayl_rgDc6Es,2722
|
|
7
|
+
codeshave/graph.py,sha256=U9yX1DUS28Y12AjgbSTuPvI7NgUId9npgEk5Wq_GRy8,2436
|
|
8
|
+
codeshave/mcp.py,sha256=arc6v9QMr4Z07n_suenWaeUa4a16XoSmRf-Ivg7XX_Y,4934
|
|
9
|
+
codeshave/parser.py,sha256=jXho3fWOvJBd5BXbC5R9OlBv7y-wVHX8FOsL3pgrQmY,6749
|
|
10
|
+
codeshave-0.1.0.dist-info/METADATA,sha256=AjHtDp7bpaPeT2VeIVADrlBMOjzf6nRAe1E8pv6RtZs,4941
|
|
11
|
+
codeshave-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
12
|
+
codeshave-0.1.0.dist-info/entry_points.txt,sha256=WhJhX4LBB5m6lGtmrJZj9VWYK-8Env8DahWgwzocTSo,49
|
|
13
|
+
codeshave-0.1.0.dist-info/top_level.txt,sha256=hI_m-fKQlcQ48_MAe3CE0dqgeVqC7lqTc44wyKCeyjY,10
|
|
14
|
+
codeshave-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
codeshave
|