@nrafinia/csmesh 0.6.0 → 0.6.1
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.
- package/README.md +31 -21
- package/package.json +1 -1
- package/scripts/install.js +4 -1
package/README.md
CHANGED
|
@@ -9,8 +9,8 @@ Built for AI coding agents and developers who are tired of multi-turn "file-hopp
|
|
|
9
9
|
|
|
10
10
|
[](https://dotnet.microsoft.com/)
|
|
11
11
|
[](https://learn.microsoft.com/en-us/dotnet/core/deploying/native-aot/)
|
|
12
|
-
[](https://github.com/nRafinia/CsMesh)
|
|
13
|
+
[](https://github.com/nRafinia/CsMesh)
|
|
14
14
|
[](LICENSE)
|
|
15
15
|
|
|
16
16
|
</div>
|
|
@@ -107,7 +107,7 @@ In layered, enterprise .NET applications, **lexical text search (`grep`, `ripgre
|
|
|
107
107
|
|
|
108
108
|
## 📊 Empirical Benchmarks
|
|
109
109
|
|
|
110
|
-
To quantify the real-world performance gains, `csmesh` was benchmarked against the standard AI agent workflow (**Ripgrep / `rg` + sequential file reads**) across a
|
|
110
|
+
To quantify the real-world performance gains, `csmesh` was benchmarked against the standard AI agent workflow (**Ripgrep / `rg` + sequential file reads**) across a private 29-project .NET solution (**1,945 symbols, 5,164 edges**, measured 2026-09-21 on csmesh 0.6.0).
|
|
111
111
|
|
|
112
112
|
The evaluation measured four critical dimensions:
|
|
113
113
|
1. **Query & Execution Latency**: Raw tool execution time and total agent turnaround time.
|
|
@@ -119,22 +119,26 @@ The evaluation measured four critical dimensions:
|
|
|
119
119
|
|
|
120
120
|
### Scenario-by-Scenario Benchmark Summary
|
|
121
121
|
|
|
122
|
-
| Workflow Scenario |
|
|
123
|
-
|
|
124
|
-
| **1. DI Implementation & Binding
|
|
125
|
-
| **2. Deep Call Chain Trace
|
|
126
|
-
| **3. Change Impact & Blast Radius
|
|
127
|
-
| **4. Multi-Hop Path Finding
|
|
128
|
-
| **5. Endpoint & Worker Discovery
|
|
129
|
-
| **6. Type Structure & Signature
|
|
130
|
-
| **7. Full Architecture Mapping
|
|
122
|
+
| Workflow Scenario | Command | Median (min–max) | csmesh tokens | Baseline | Reduction |
|
|
123
|
+
|:---|:---|---:|---:|:---|---:|
|
|
124
|
+
| **1. DI Implementation & Binding** | `csmesh impl IOrderRepository` | 27.6 ms (26.9–43.2) | 97 | ~1,500 tokens via grep + read | ~94% |
|
|
125
|
+
| **2. Deep Call Chain Trace** | `csmesh trace OrderEndpoints.CreateOrderAsync --depth 2` | 27.8 ms (26.6–29.9) | 288 | ~4,000 tokens via 5–7 turns | ~93% |
|
|
126
|
+
| **3. Change Impact & Blast Radius** | `csmesh blast-radius OrderService.UpdateAsync` | 27.4 ms (26.7–29.6) | 105 | 4–6 turns over 24+ noisy grep hits (no token baseline) | n/a |
|
|
127
|
+
| **4. Multi-Hop Path Finding** | `csmesh path OrderEndpoints.CreateOrderAsync OrderWriter` | 29.7 ms (27.4–45.4) | 115 | impossible with grep (no token baseline) | n/a |
|
|
128
|
+
| **5. Endpoint & Worker Discovery** | `csmesh entrypoints` | 24.8 ms (23.5–32.3) | 738 | repeated greps + manual parsing (no token baseline) | n/a |
|
|
129
|
+
| **6. Type Structure & Signature** | `csmesh context OrderRecord` | 27.7 ms (26.5–30.5) | 478 | locate and read the whole file (no token baseline) | n/a |
|
|
130
|
+
| **7. Full Architecture Mapping** | `csmesh map` | 28.8 ms (27.5–41.6) | 766 | read `.slnx` + 29 `.csproj` files (no token baseline) | n/a |
|
|
131
|
+
|
|
132
|
+
Symbol names above are placeholders; the numbers were measured on the real codebase with symbols of the same shape. Median of 20 warm runs (graph pre-indexed and held in the OS file cache) on a NativeAOT win-x64 build of csmesh 0.6.0, 2026-09-21, on a 13th Gen Intel Core i7-13620H (10 cores / 16 threads, 48 GB RAM, NVMe SSD). Token counts use csmesh's own estimator at roughly four characters per token.
|
|
131
133
|
|
|
132
134
|
---
|
|
133
135
|
|
|
134
136
|
### Deep-Dive Real-World Scenarios
|
|
135
137
|
|
|
138
|
+
Times below are the same 2026-09-21 medians as the table above, measured on the **NativeAOT win-x64** channel; the framework-dependent `dotnet tool` channel pays JIT warm-up and is slower.
|
|
139
|
+
|
|
136
140
|
#### 1. Interface Implementation & Runtime DI Resolution
|
|
137
|
-
* **With `csmesh impl IOrderRepository --budget 300` (
|
|
141
|
+
* **With `csmesh impl IOrderRepository --budget 300` (27.6 ms, NativeAOT win-x64):**
|
|
138
142
|
Identifies all 3 concrete implementations in a single glance: tags `SqlOrderRepository` with `[di:scoped]` along with the exact file and line where it was bound in the IoC container, while clearly marking `SpyOrderRepository` and `InMemoryOrderRepository` as test doubles.
|
|
139
143
|
* **Without `csmesh`:**
|
|
140
144
|
- *Turn 1:* Run `rg ":\s*IOrderRepository\b"` to find inheriting classes (returns multiple classes, but cannot indicate which one is registered in production).
|
|
@@ -142,40 +146,40 @@ The evaluation measured four critical dimensions:
|
|
|
142
146
|
- *Turn 3:* Open the DI module or test fixture to verify which instance actually executes at runtime.
|
|
143
147
|
|
|
144
148
|
#### 2. Forward Call Chain Tracing Across Interface Boundaries
|
|
145
|
-
* **With `csmesh trace OrderEndpoints.CreateOrderAsync --depth 2` (
|
|
149
|
+
* **With `csmesh trace OrderEndpoints.CreateOrderAsync --depth 2` (27.8 ms, NativeAOT win-x64):**
|
|
146
150
|
Follows execution seamlessly across decoupled interface abstractions. Traces `IAuthorizationService.AuthorizeAsync` directly to its concrete implementation `AuthorizationService.AuthorizeAsync`, continuing downstream to `AuditLogger.LogAsync` and `AppDbContext.SaveChangesAsync`.
|
|
147
151
|
* **Without `csmesh`:**
|
|
148
152
|
The agent must open the endpoint file (~100 lines), observe the interface call, search for the interface declaration, grep for implementations, open the implementation source, and repeat this cycle until reaching the persistence layer—burning 5 to 7 turns and 30+ seconds of reasoning time.
|
|
149
153
|
|
|
150
154
|
#### 3. Blast Radius & Change Impact Analysis
|
|
151
|
-
* **With `csmesh blast-radius OrderRepository.UpdateAsync --budget 800` (
|
|
155
|
+
* **With `csmesh blast-radius OrderRepository.UpdateAsync --budget 800` (27.4 ms, NativeAOT win-x64):**
|
|
152
156
|
Computes the reverse transitive dependency graph: reveals that modifying `UpdateAsync` impacts 18 internal members, 1 public HTTP route (`OrderEndpoints.CreateOrderAsync`), and 14 tests across 4 separate projects—clearly categorizing test callers vs. production entrypoints.
|
|
153
157
|
* **Without `csmesh`:**
|
|
154
158
|
Running `rg "\bUpdateAsync\b"` returns dozens of raw matching lines across interfaces, mocks, comments, and unrelated classes. Text search cannot determine which root endpoints ultimately depend on this method without exhaustive manual back-tracing.
|
|
155
159
|
|
|
156
160
|
#### 4. Multi-Hop Path Finding
|
|
157
|
-
* **With `csmesh path OrderEndpoints.CreateOrderAsync OrderRepository.UpdateAsync` (
|
|
161
|
+
* **With `csmesh path OrderEndpoints.CreateOrderAsync OrderRepository.UpdateAsync` (29.7 ms, NativeAOT win-x64):**
|
|
158
162
|
```text
|
|
159
163
|
OrderEndpoints.CreateOrderAsync
|
|
160
164
|
-> OrderService.ProcessOrderAsync
|
|
161
165
|
-> IOrderRepository.UpdateAsync
|
|
162
166
|
-> SqlOrderRepository.UpdateAsync [impl, di-bound]
|
|
163
167
|
```
|
|
164
|
-
Resolves the exact 4-hop invocation path through services and DI container registrations in
|
|
168
|
+
Resolves the exact 4-hop invocation path through services and DI container registrations in 29.7 ms—a task fundamentally beyond the capabilities of text search.
|
|
165
169
|
|
|
166
170
|
---
|
|
167
171
|
|
|
168
172
|
### Core Takeaways
|
|
169
173
|
|
|
170
|
-
1. **Semantic Intelligence vs. Lexical Speed:** While `ripgrep` searches text in 30–50 ms, its output is **lexical, not semantic**. `csmesh` answers in
|
|
174
|
+
1. **Semantic Intelligence vs. Lexical Speed:** While `ripgrep` searches text in 30–50 ms, its output is **lexical, not semantic**. `csmesh` answers in **~25–30 ms** (median of 20 warm runs on the NativeAOT win-x64 channel, measured 2026-09-21 on csmesh 0.6.0), but returns definitive, actionable architectural conclusions rather than raw strings.
|
|
171
175
|
2. **Eliminating the Agent Turn Latency Bottleneck:** In AI agent interactions, the dominant latency cost is LLM inference and reasoning per turn (often 5–15 seconds per round-trip). By collapsing 4 to 8 file-hunting turns into **1 single shell command**, `csmesh` cuts total agent task completion time by **over 80%**.
|
|
172
|
-
3. **Context Window Hygiene:** Replacing full source file dumps with compact graph edges saves
|
|
176
|
+
3. **Context Window Hygiene:** Replacing full source file dumps with compact graph edges saves **~93–94% of token spend** in the two measured scenarios that have a token baseline (DI binding and call-chain trace), preserving the model's context window for actual implementation rather than navigation. The other scenarios were measured as csmesh token counts only, against qualitative baselines.
|
|
173
177
|
|
|
174
178
|
---
|
|
175
179
|
|
|
176
180
|
## ✨ Key Features
|
|
177
181
|
|
|
178
|
-
- **🚀 Native AOT & .NET 10 Ready:** No JIT warm-up, no runtime to install, and lookup tables frozen once at load (`System.Collections.Frozen`) so a query walks the graph instead of rebuilding indexes. Median query on
|
|
182
|
+
- **🚀 Native AOT & .NET 10 Ready:** No JIT warm-up, no runtime to install, and lookup tables frozen once at load (`System.Collections.Frozen`) so a query walks the graph instead of rebuilding indexes. Median query on the measured 29-project solution: ~28 ms (median of 20 warm runs, NativeAOT win-x64, csmesh 0.6.0, 2026-09-21), dominated by graph load, not by the walk.
|
|
179
183
|
- **🎨 Blazor & Razor Component Intelligence:** Indexes Blazor components, `@code` methods, component parameters, and Razor Pages / MVC views. Automatically discovers `@page "/..."` routes as HTTP entrypoints and accurately maps line numbers back to `.razor` and `.cshtml` source files via Roslyn `#line` directives.
|
|
180
184
|
- **🛡️ Output Budget (`--budget N`):** A hard cap on estimated output tokens. Prevents agent context exhaustion by exiting with actionable tips when a query is too broad.
|
|
181
185
|
- **💉 DI & IoC Container Intelligence:** Reads service registrations in every form they take — two-argument, `typeof` pairs, keyed, factory lambdas, and alias registrations such as `sp => sp.GetRequiredService<Concrete>()` — and ranks the class the container actually returns ahead of the ones nobody registered.
|
|
@@ -233,6 +237,8 @@ curl -fsSL https://raw.githubusercontent.com/nRafinia/CsMesh/main/install.sh | s
|
|
|
233
237
|
irm https://raw.githubusercontent.com/nRafinia/CsMesh/main/install.ps1 | iex
|
|
234
238
|
```
|
|
235
239
|
|
|
240
|
+
The install scripts download the prebuilt Native AOT binary for your OS and architecture — `win-x64`, `win-arm64`, `linux-x64`, `linux-arm64`, `osx-arm64`, `osx-x64` — and fall back to the .NET global tool when no asset matches.
|
|
241
|
+
|
|
236
242
|
---
|
|
237
243
|
|
|
238
244
|
### 1. As a Global .NET Tool
|
|
@@ -249,6 +255,8 @@ dotnet tool install --global --add-source ./src/CsMesh/bin/Release CsMesh
|
|
|
249
255
|
dotnet tool update --global CsMesh
|
|
250
256
|
```
|
|
251
257
|
|
|
258
|
+
From 0.6.1 the tool package is RID-specific: on `win-x64`, `win-arm64`, `linux-x64`, `linux-arm64`, `osx-arm64` and `osx-x64`, `dotnet tool install` fetches the Native AOT binary. On any other platform it falls back to the framework-dependent build.
|
|
259
|
+
|
|
252
260
|
### 2. Via npm / npx
|
|
253
261
|
```bash
|
|
254
262
|
Bash
|
|
@@ -259,6 +267,8 @@ npx @nrafinia/csmesh --help
|
|
|
259
267
|
npm install -g @nrafinia/csmesh
|
|
260
268
|
```
|
|
261
269
|
|
|
270
|
+
`npx` and `npm install -g` download the prebuilt Native AOT binary for your platform (the six RIDs listed above) from the GitHub release, so no .NET runtime is needed.
|
|
271
|
+
|
|
262
272
|
### 3. As a Standalone Native AOT Binary (Zero Runtime Dependency)
|
|
263
273
|
|
|
264
274
|
You can compile a single, standalone binary with zero dependencies on the .NET SDK:
|
|
@@ -274,7 +284,7 @@ dotnet publish src/CsMesh/CsMesh.csproj -c Release -r linux-x64 -p:PublishAot=tr
|
|
|
274
284
|
dotnet publish src/CsMesh/CsMesh.csproj -c Release -r osx-arm64 -p:PublishAot=true
|
|
275
285
|
```
|
|
276
286
|
|
|
277
|
-
The resulting binary in `bin/Release/net10.0/<rid>/publish/`
|
|
287
|
+
The resulting binary in `bin/Release/net10.0/<rid>/publish/` runs on machines without .NET installed and, on the measured NativeAOT win-x64 channel, answers a warm query in ~28 ms median (csmesh 0.6.0, 2026-09-21).
|
|
278
288
|
|
|
279
289
|
---
|
|
280
290
|
|
package/package.json
CHANGED
package/scripts/install.js
CHANGED
|
@@ -9,8 +9,11 @@ const arch = process.arch;
|
|
|
9
9
|
|
|
10
10
|
const targets = {
|
|
11
11
|
'win32-x64': { file: 'csmesh-win-x64.zip', bin: 'csmesh.exe' },
|
|
12
|
+
'win32-arm64': { file: 'csmesh-win-arm64.zip', bin: 'csmesh.exe' },
|
|
12
13
|
'linux-x64': { file: 'csmesh-linux-x64.tar.gz', bin: 'csmesh' },
|
|
13
|
-
'
|
|
14
|
+
'linux-arm64': { file: 'csmesh-linux-arm64.tar.gz', bin: 'csmesh' },
|
|
15
|
+
'darwin-arm64': { file: 'csmesh-osx-arm64.tar.gz', bin: 'csmesh' },
|
|
16
|
+
'darwin-x64': { file: 'csmesh-osx-x64.tar.gz', bin: 'csmesh' }
|
|
14
17
|
};
|
|
15
18
|
|
|
16
19
|
const key = `${platform}-${arch}`;
|