lady-lens 1.2.0 → 1.6.8
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/DOCUMENTATIE.md +430 -408
- package/README.md +405 -357
- package/bin/lens.mjs +200 -184
- package/core/bench/budget.js +31 -0
- package/core/bench/command.js +59 -0
- package/core/bench/compare.js +50 -0
- package/core/bench/environment.js +29 -0
- package/core/bench/index.js +11 -0
- package/core/bench/measure.js +49 -0
- package/core/bench/operations.js +63 -0
- package/core/bench/processTimes.js +49 -0
- package/core/bench/report.js +35 -0
- package/core/bench/runBench.js +120 -0
- package/core/bench/scaleRepo.js +78 -0
- package/core/bench/store.js +31 -0
- package/core/branches/branchDiff.js +4 -10
- package/core/branches/branchImpact.js +9 -4
- package/core/branches/changedFunctions.js +68 -65
- package/core/branches/compare.js +37 -22
- package/core/branches/readSources.js +23 -0
- package/core/configuration/frontmatter.js +146 -186
- package/core/configuration/index.js +5 -4
- package/core/configuration/toolLimits.js +40 -0
- package/core/daemonCall/index.js +64 -0
- package/core/discussions/mcp/discussionTools.js +170 -164
- package/core/discussions/model/nodes.js +142 -151
- package/core/discussions/storage/markdownExtractor.js +33 -38
- package/core/eval/graphEval.js +172 -163
- package/core/git/fakeGit.js +140 -130
- package/core/git/index.js +55 -9
- package/core/graph/adapters/ladybug/configIndexer.js +107 -109
- package/core/graph/adapters/ladybug/directQueries.js +161 -164
- package/core/graph/adapters/ladybug/index.js +30 -28
- package/core/graph/adapters/ladybug/ladybugGraphStore.js +178 -181
- package/core/graph/adapters/ladybug/ladybugIndexer.js +89 -71
- package/core/graph/adapters/ladybug/ladybugMarkdownIndexer.js +105 -105
- package/core/graph/adapters/ladybug/repositoryStore.js +200 -200
- package/core/graph/adapters/ladybug/writeBatches.js +54 -0
- package/core/graph/adapters/memory/directQueries.js +184 -178
- package/core/graph/adapters/memory/repositoryStore.js +149 -128
- package/core/graph/model/graphEdges.js +77 -0
- package/core/graph/model/graphLookup.js +32 -0
- package/core/graph/model/graphModel.js +175 -209
- package/core/graph/model/graphRows.js +109 -61
- package/core/graph/model/graphValidation.js +67 -69
- package/core/graph/query/answerNode.js +27 -0
- package/core/graph/query/architectureMetrics.js +165 -126
- package/core/graph/query/codeHealth.js +188 -177
- package/core/graph/query/docComment.js +60 -0
- package/core/graph/query/folderParts.js +79 -0
- package/core/graph/query/folderPredicates.js +89 -0
- package/core/graph/query/folderView.js +161 -171
- package/core/graph/query/folderViewRender.js +129 -0
- package/core/graph/query/functionView.js +200 -175
- package/core/graph/query/graphContext.js +109 -99
- package/core/graph/query/graphQuery.js +160 -233
- package/core/graph/query/graphRank.js +155 -177
- package/core/graph/query/graphSemantic.js +228 -238
- package/core/graph/query/healthIssues.js +161 -0
- package/core/graph/query/hubsAndBridges.js +81 -63
- package/core/graph/query/impact.js +187 -161
- package/core/graph/query/importCycles.js +94 -62
- package/core/graph/query/importLookup.js +185 -221
- package/core/graph/query/index.js +13 -11
- package/core/graph/query/queryFreshness.js +47 -0
- package/core/graph/query/questionIntent.js +117 -0
- package/core/graph/query/rankCorrections.js +85 -0
- package/core/graph/query/rankTokens.js +59 -0
- package/core/graph/query/searchIndex.js +69 -0
- package/core/graph/query/statePlaces.js +90 -0
- package/core/graph/repository/graphRepository.js +128 -125
- package/core/graph/repository/projectGraphGate.js +104 -83
- package/core/graph/sync/codeFacts.js +200 -215
- package/core/graph/sync/commentWords.js +12 -0
- package/core/graph/sync/contributors.js +24 -7
- package/core/graph/sync/designSmellAdvice.js +20 -0
- package/core/graph/sync/designSmells.js +3 -0
- package/core/graph/sync/documentRelations.js +133 -81
- package/core/graph/sync/fileEntity.js +7 -2
- package/core/graph/sync/fileSmells.js +137 -0
- package/core/graph/sync/functionComplexity.js +193 -106
- package/core/graph/sync/functionSmells.js +166 -0
- package/core/graph/sync/gitHistory.js +42 -30
- package/core/graph/sync/graphSync.js +54 -35
- package/core/graph/sync/headCommit.js +15 -3
- package/core/graph/sync/index.js +12 -10
- package/core/graph/sync/languages/blocks.js +10 -8
- package/core/graph/sync/languages/docker.js +118 -107
- package/core/graph/sync/languages/engine.js +193 -185
- package/core/graph/sync/languages/index.js +3 -1
- package/core/graph/sync/languages/infra.js +139 -91
- package/core/graph/sync/languages/jsonConfig.js +73 -0
- package/core/graph/sync/languages/terraformConfig.js +66 -0
- package/core/graph/sync/languages/tomlConfig.js +54 -0
- package/core/graph/sync/languages/web.js +133 -141
- package/core/graph/sync/mendix.js +97 -124
- package/core/graph/sync/mendixExport.js +127 -0
- package/core/graph/sync/mxcli.js +54 -0
- package/core/graph/sync/projectRelations.js +136 -43
- package/core/language/fuzzy.js +57 -51
- package/core/language/lexicon.js +103 -79
- package/core/language/lexiconValidation.js +71 -46
- package/core/mcp/agentInstall.js +192 -156
- package/core/mcp/daemon.js +18 -12
- package/core/mcp/handlers/branchDiff.js +6 -0
- package/core/mcp/handlers/config.js +4 -3
- package/core/mcp/handlers/index.js +2 -2
- package/core/mcp/handlers/repoSync.js +12 -5
- package/core/mcp/httpServer.js +153 -278
- package/core/mcp/index.js +38 -38
- package/core/mcp/managementSchemas.js +193 -191
- package/core/mcp/mcpDashboard.html +171 -0
- package/core/mcp/mcpToolRow.html +1 -0
- package/core/mcp/mendixSchemas.js +19 -0
- package/core/mcp/policyInstall.js +84 -77
- package/core/mcp/server.js +141 -130
- package/core/mcp/streamableHttp.js +4 -2
- package/core/mcp/toolRoutes.js +34 -33
- package/core/mendix/bson.js +71 -0
- package/core/mendix/elementDiff.js +92 -0
- package/core/mendix/flows.js +83 -0
- package/core/mendix/index.js +6 -0
- package/core/mendix/mendixDiff.js +107 -0
- package/core/mendix/modelReader.js +90 -0
- package/core/observability/debugLog.js +52 -23
- package/core/observability/index.js +3 -2
- package/core/observability/profiler.js +5 -1
- package/core/observability/tracing.js +114 -0
- package/core/repository/gitignoreRules.js +96 -0
- package/core/repository/index.js +18 -16
- package/core/repository/projectScanner.js +66 -62
- package/core/repository/projectSettings.js +141 -125
- package/core/repository/registry.js +152 -138
- package/core/search/budget.js +98 -17
- package/core/search/callFlow.js +137 -0
- package/core/search/chunkReader.js +198 -139
- package/core/search/codeHealth.js +67 -68
- package/core/search/codeHistory.js +32 -0
- package/core/search/diffImpact.js +72 -58
- package/core/search/graphModelLoader.js +156 -148
- package/core/search/graphQuery.js +199 -84
- package/core/search/graphQueryArgs.js +33 -0
- package/core/search/grepSearch.js +178 -122
- package/core/search/index.js +133 -116
- package/core/search/queryFlow.js +101 -85
- package/core/search/queryPlaces.js +21 -0
- package/core/search/schemas.js +135 -122
- package/core/search/searchView.js +109 -95
- package/core/search/stackTrace.js +116 -0
- package/core/search/toolLimit.js +41 -0
- package/core/update/index.js +3 -0
- package/core/update/lensNode.js +41 -0
- package/core/update/lensUpdate.js +47 -0
- package/index.js +93 -90
- package/package.json +105 -102
- package/skills/lady-lens/SKILL.md +29 -28
- package/skills/lady-lens/lens-instructions.md +14 -11
- package/skills/lady-lens-mendix/SKILL.md +53 -40
- package/ui/graph-ui-context.html +84 -0
- package/ui/graph-ui-graph.html +87 -0
- package/ui/graph-ui-health.html +27 -0
- package/ui/graph-ui-nav.html +54 -0
- package/ui/graph-ui-trace.html +65 -0
- package/ui/graph-ui.css +163 -122
- package/ui/graph-ui.html +178 -200
- package/ui/graph-ui.mjs +162 -73
package/README.md
CHANGED
|
@@ -1,357 +1,405 @@
|
|
|
1
|
-
# lady-lens
|
|
2
|
-
|
|
3
|
-
A code graph for repositories in many languages: where a function is defined, who imports a file, what a function does and which tests and stories touch it, what was decided. Local, on [Ladybug](https://www.npmjs.com/package/@ladybugdb/core), no model needed. See [Supported languages](#supported-languages).
|
|
4
|
-
|
|
5
|
-
> 📖 **Documentation**: see [DOCUMENTATIE.md](DOCUMENTATIE.md) (written in English) for the full guide to architecture, all API ports (through MCP and npm), configuration through `config.json` and code examples.
|
|
6
|
-
|
|
7
|
-
## Where it comes from
|
|
8
|
-
|
|
9
|
-
lady-lens grew inside the build of our own coding agent, Kura. We used it there to give the agent a better, narrower context: the right files, functions and decisions instead of everything. It turned out so handy and so fast that we exported it as its own package. Built locally, not published.
|
|
10
|
-
|
|
11
|
-
## Setup
|
|
12
|
-
|
|
13
|
-
Needs Node.js 18 or newer. Run these steps once, in order.
|
|
14
|
-
|
|
15
|
-
**1. Install lady-lens**
|
|
16
|
-
|
|
17
|
-
```
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
lens
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
```
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
lens install
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
lens
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
lens
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
lens
|
|
68
|
-
lens
|
|
69
|
-
lens
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
lens
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
lens
|
|
78
|
-
lens
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
```
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
```
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
```
|
|
356
|
-
|
|
357
|
-
|
|
1
|
+
# lady-lens
|
|
2
|
+
|
|
3
|
+
A code graph for repositories in many languages: where a function is defined, who imports a file, what a function does and which tests and stories touch it, what was decided. Local, on [Ladybug](https://www.npmjs.com/package/@ladybugdb/core), no model needed. See [Supported languages](#supported-languages).
|
|
4
|
+
|
|
5
|
+
> 📖 **Documentation**: see [DOCUMENTATIE.md](DOCUMENTATIE.md) (written in English) for the full guide to architecture, all API ports (through MCP and npm), configuration through `config.json` and code examples.
|
|
6
|
+
|
|
7
|
+
## Where it comes from
|
|
8
|
+
|
|
9
|
+
lady-lens grew inside the build of our own coding agent, Kura. We used it there to give the agent a better, narrower context: the right files, functions and decisions instead of everything. It turned out so handy and so fast that we exported it as its own package. Built locally, not published.
|
|
10
|
+
|
|
11
|
+
## Setup
|
|
12
|
+
|
|
13
|
+
Needs Node.js 18 or newer; the Mendix MDL export needs 22.13 or newer (see [Another Node for lens](#another-node-for-lens)). Run these steps once, in order.
|
|
14
|
+
|
|
15
|
+
**1. Install lady-lens** from npm:
|
|
16
|
+
|
|
17
|
+
```
|
|
18
|
+
npm install -g lady-lens
|
|
19
|
+
lens v # prints the version: `lens` is on your PATH
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
From source instead (development, or a version that is not published yet): run `npm install` and `npm run pack` in this folder, which builds `dist\lady-lens-<version>.tgz`, and install that with `npm install -g .\dist\lady-lens-<version>.tgz` (later: `lens update .\dist\lady-lens-<version>.tgz`). `npm link` makes `lens` run straight from this folder.
|
|
23
|
+
|
|
24
|
+
**2. Register your repository and index it:**
|
|
25
|
+
|
|
26
|
+
```
|
|
27
|
+
lens add C:\git\my-project # registers the repo and runs the first sync
|
|
28
|
+
lens list # check that it is there
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
**3. Connect your AI agent** (pick one or both):
|
|
32
|
+
|
|
33
|
+
```
|
|
34
|
+
lens install # MCP entry (stdio) in every agent found; or name one: lens install vscode
|
|
35
|
+
lens install --skill # the Lady-lens workflow skill for those agents
|
|
36
|
+
lens install --mendix # the Mendix skill (search .mpr content via .mxcli/mdl, change it with mxcli)
|
|
37
|
+
lens install skill-mendix vscode claude-code # the same, only for those agents
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
`lens install --dry-run` shows what would change and writes nothing. Restart the agent afterwards (in VS Code: *MCP: List Servers* or reload the window).
|
|
41
|
+
|
|
42
|
+
**4. Or run one background service for all projects** (the HTTP alternative to step 3):
|
|
43
|
+
|
|
44
|
+
```
|
|
45
|
+
lens mcp -d # MCP on http://127.0.0.1:4318/mcp, UI on http://127.0.0.1:4317
|
|
46
|
+
lens status # is it running?
|
|
47
|
+
lens stop # stop it
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
In VS Code add it to `mcp.json` as `{ "servers": { "lady-lens": { "type": "http", "url": "http://127.0.0.1:4318/mcp?repo=C:/git/my-project" } } }`. See [MCP Configuration](#mcp-configuration-model-context-protocol) for the other agents.
|
|
51
|
+
|
|
52
|
+
**5. Update later** with one command:
|
|
53
|
+
|
|
54
|
+
```
|
|
55
|
+
lens update # the newest version from npm
|
|
56
|
+
lens update 1.2.8 # a given version
|
|
57
|
+
lens update C:\path\lady-lens-1.2.8.tgz # a package file (a machine without npm access, or a build from source)
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
`lens update` stops every lens process (on Windows a running lens keeps the graph database module open, and npm cannot replace it), installs the package, lets the new lens re-register itself in the agents where it was registered and copy the installed skills and instruction files again (`lens install --refresh`: the `SKILL.md` files and `~/.lady-lens/lens-instructions.md`; your own `CLAUDE.md` or `AGENTS.md` only holds a link to it), and starts the daemon again if it ran. It adds nothing you did not install. Reconnect your agents afterwards (Claude Code: `/mcp`).
|
|
61
|
+
|
|
62
|
+
### Another Node for lens
|
|
63
|
+
|
|
64
|
+
The Mendix MDL export needs Node 22.13 or newer (`node:sqlite`). When your projects need an older Node on PATH (nvm), let only lens run on a newer one; PATH and nvm stay as they are:
|
|
65
|
+
|
|
66
|
+
```
|
|
67
|
+
lens node "C:\Program Files\nodejs\node.exe" # lens, its daemon and the agent registrations now run on that Node
|
|
68
|
+
lens node # which Node lens runs on
|
|
69
|
+
lens node --clear # back to the Node on PATH
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
The choice is kept in `~/.lady-lens/lens.json`: it holds at once, in every terminal and for agents started from the desktop (`setx` only reaches terminals started later). The package stays where npm installed it. Ladybug's native module works on every Node version.
|
|
73
|
+
|
|
74
|
+
## Use
|
|
75
|
+
|
|
76
|
+
```
|
|
77
|
+
lens sync # index this repo (incremental; --full re-indexes everything; --debug logs every step to ~/.lady-lens/logs)
|
|
78
|
+
lens mcp # MCP server (Streamable HTTP on /mcp, UI dashboard on 4317)
|
|
79
|
+
lens mcp -d # run MCP + UI in background (detached)
|
|
80
|
+
lens stop # stop background lady-lens daemon
|
|
81
|
+
lens ps # list tracked daemon PIDs per folder
|
|
82
|
+
lens v # print the installed version
|
|
83
|
+
lens ask functionView '{"symbol":"createGraphSync"}'
|
|
84
|
+
lens ask importedBy '{"file":"core/graph/index.js"}'
|
|
85
|
+
lens ask graph_query '{"query":"plan review"}'
|
|
86
|
+
lens ask graph_query '{"query":"plan review","kind":"doc"}' # only the documentation
|
|
87
|
+
lens ui # http://127.0.0.1:4317: search, stack trace, nodes coloured per type, code and docs
|
|
88
|
+
lens list # every repo lens knows
|
|
89
|
+
lens add <dir> # register a repository and sync
|
|
90
|
+
lens remove <id|dir> # unregister a repository
|
|
91
|
+
lens tools # every question and what it answers
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
When the daemon runs (`lens mcp -d`), `lens ask` for a registered repository goes through it: the daemon has lady-lens and the graph loaded, so a question costs one HTTP call (about 0.4 s instead of about 1 s). Without a daemon, for a repository it does not serve, or with `--db`, `lens ask` runs the tool itself.
|
|
95
|
+
|
|
96
|
+
`--repo <dir>` asks about another repo than the current folder; `lens ui --port 5000` picks another port.
|
|
97
|
+
|
|
98
|
+
The four tabs of the dashboard are one whole: there is one place (tab, file, line) for the page, kept in the URL (`#tab=…&path=…&line=…`), so the browser's Back/Forward, the ◀ ▶ buttons and the crumbs under the tabs step through where you were, and a copied link opens the same place. Every file or function in any tab is a link to it.
|
|
99
|
+
|
|
100
|
+
- **Search & Explorer**: the code with the line you went to; functions with health issues are marked ⚠ in the gutter, the file's and the function's issues stand above the code. Under it: the function at the line (purpose, callers, calls, a call tree that opens per level with a chosen depth, tests, the documents that name it), the file's imports both ways, and, loaded last, its history: the commits that changed the function (else the file), who changed it last, the files that usually change with it, and a hotspot sign (commits × lines in the project's top 10).
|
|
101
|
+
- **Graph Network**: at a function, the flow diagram of its call chain (callers left, callees right, depth and direction to choose); a click on a function goes there, **Mermaid** shows and copies the text for a document or ticket. At a file or without a place: the overview of files.
|
|
102
|
+
- **Architecture & Health**: every file and function opens its code, a function name its flow diagram.
|
|
103
|
+
- **Stacktrace**: see below; a frame opens its code or its flow diagram, where the frames of the trace are marked.
|
|
104
|
+
|
|
105
|
+
In the dashboard's **Stacktrace** tab you paste a Node, .NET, Python or Java stack trace: each frame shows its file, line, function and the code around the line. Paths from another machine (`C:\build\...`, `/home/ci/...`) match the project file with the longest equal tail of folders; several equal matches let you choose, no match says "niet gevonden", library frames (`node_modules`, `site-packages`, frames without a file) are folded away. The page posts the trace to `POST /api/trace` (follows `?repo=`).
|
|
106
|
+
|
|
107
|
+
## Questions
|
|
108
|
+
|
|
109
|
+
Every tool that returns a list takes `limit`: how many items its main list holds (`graph_query` 20 nodes, `grep` 50 matches, `glob` 200 paths, `importedBy`/`imports`/`exports` 200, `searchView` 100, `diff_impact` 50, `definedIn` 50, `folderView` 40 parts, `functionView` 20 callers, tests and stories, `health` 20 per list, `discussion_query` 10). Without `limit` the default holds; the setting `LENS_<TOOL>_LIMIT` (`LENS_GRAPH_QUERY_LIMIT`, `LENS_IMPORTED_BY_LIMIT`, or `env` in the lens configuration of a repository) changes it. A cut list says so in `truncated` and `limited`. The context budget still caps the whole answer.
|
|
110
|
+
|
|
111
|
+
| Tool | Answers |
|
|
112
|
+
|---|---|
|
|
113
|
+
| `definedIn` | where a function or name is defined, with lines |
|
|
114
|
+
| `functionView` | what a function does: definition and lines, purpose, callers, tests (with test names), stories; bound (`resolved`) and unbound (`unresolved`) calls, with "niet bewezen leeg" when nothing is bound but the name appears; for a class its methods (`children`) and subclasses (`inheritors`); `maxSites` for more than 5 lines per file |
|
|
115
|
+
| `diff_impact` | what my change touches: the functions the work not committed yet (or a range `from`..`to`) changes, with callers, tests, complexity and test gaps, riskiest first |
|
|
116
|
+
| `importedBy` / `imports` | who imports a file / what it imports |
|
|
117
|
+
| `exports` | what a file exports |
|
|
118
|
+
| `exists` | whether a file exists, and where a file with that name does |
|
|
119
|
+
| `cross_repo_search` | one search over all registered projects, or `repos: [...]`; results per project, unregistered names in `unknown` |
|
|
120
|
+
| `graph_query` | files about a subject, 20 candidates by default for a caller or its model to choose from (over the context budget edges, `context` and `provenance` go first, and candidates after the first become `path`, `purpose` and a few `exports`); `kind: "doc"` only documentation (for a file path: the documents that name it first, `mentions` and `lines`); `history: true` also superseded decisions; a `node` gets its `consequences` and `risks`, and a one-hop answer says `total` and `truncated` |
|
|
121
|
+
| `grep`, `glob`, `read_chunk` | text search, paths, and lines of a file, with the same exclusions as the graph |
|
|
122
|
+
| `config_grep` | config-only search, including `.csproj` and reference-manager XML |
|
|
123
|
+
| `config_references` | find which config files reference a package, project, or functional block by name |
|
|
124
|
+
| `config_update` | safely replace one config file and refresh its graph facts; supports `expectedHash` |
|
|
125
|
+
| `repo_sync` | index the repository; records the branch and commit and reports `commitsSince`; `branch: "<name>"` indexes another branch into its own scope `branch:<name>` without checking it out |
|
|
126
|
+
| `branch_diff` | what branch `to` changes since its merge-base with `from`: files and functions added, removed, modified, renamed, plus changed import and call relations |
|
|
127
|
+
| `mendix_diff` | Mendix model changes of a branch, read from git (no checkout, no mxcli; old single-file .mpr and mprcontents/): commits, changed documents with module, folder, name and type, every added, deleted or modified element with each property before and after, and for a microflow or nanoflow the flow graph before and after with a status per node and sequence flow. Data for a client that shows it (an extension); needs Node 22.13+ (`lens node`) |
|
|
128
|
+
| `branch_impact` | what a change on one branch (e.g. a bugfix on `release`) means for another: functions still used there, overlap, shared files, text merge conflicts |
|
|
129
|
+
| `commit_show` | what one commit changed (files and functions against its first parent) |
|
|
130
|
+
| `function_history` | the commits that added, modified or removed one function; without `name` every commit that touched the file |
|
|
131
|
+
| `health` | test reach, cycles, boundaries, hotspots, coupling; with `hubs: true` / `bridges: true` also the files with the most neighbours and the files on the most shortest paths |
|
|
132
|
+
|
|
133
|
+
## Branches and commits
|
|
134
|
+
|
|
135
|
+
The graph knows which branch and commit it was built on. After every sync a `Branch` node points to its `Commit` (`HEAD_AT`), and `repo_sync` reports how many commits came in since the last sync on that branch. Discussions are stored with the commit and branch they were made on (`CREATED_AT`, `ON_BRANCH`). A discussion keeps its source links when you switch to a branch where the file does not exist; `discussion_query` then shows the source as "not on this branch" and where it does exist. Everything reads git directly and never checks a branch out.
|
|
136
|
+
|
|
137
|
+
Compare before you merge:
|
|
138
|
+
|
|
139
|
+
```
|
|
140
|
+
branch_diff { "from": "main", "to": "feature-x" }
|
|
141
|
+
branch_impact { "change": "release", "against": "feature-x" }
|
|
142
|
+
commit_show { "commit": "263e4279" }
|
|
143
|
+
mendix_diff { "from": "main", "to": "bugfix/1234-wrong-proposed-destination" }
|
|
144
|
+
diff_impact { } # the work not committed yet
|
|
145
|
+
diff_impact { "from": "main" } # this branch since it left main
|
|
146
|
+
function_history { "name": "createGraphSync", "file": "core/graph/sync/graphSync.js" }
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
Git is started in one place only (`core/git`). Tests can use `createFakeGit` instead of a real repository; `test/gitPort.contract.test.js` keeps the two in line.
|
|
150
|
+
|
|
151
|
+
## MCP Configuration (Model Context Protocol)
|
|
152
|
+
|
|
153
|
+
lady-lens can be used by AI coding assistants (Antigravity, Cursor, Claude Desktop, Claude Code, Cline, Roo Code) as a native MCP server.
|
|
154
|
+
|
|
155
|
+
### Quick install (recommended)
|
|
156
|
+
|
|
157
|
+
```bash
|
|
158
|
+
lens install # every agent found on this machine
|
|
159
|
+
lens install cursor vscode # or name them: claude-code, claude-desktop, cursor, windsurf, gemini-cli, antigravity, antigravity-cli, vscode, codex, vibe
|
|
160
|
+
lens install --dry-run # show what would change, write nothing
|
|
161
|
+
lens install --skill # install the Lady-lens workflow skill for detected agents
|
|
162
|
+
lens install --skill --dry-run
|
|
163
|
+
lens uninstall # remove lady-lens again
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
This adds a stdio entry (absolute `node` path, no daemon, no port) to each agent's MCP config, keeps its other servers, and saves the old file as `<file>.lady-lens.bak`. Restart the agent afterwards. A config with comments (JSONC) is reported and left untouched.
|
|
167
|
+
|
|
168
|
+
`lens install --skill` installs `skills/lady-lens/SKILL.md` in detected Claude, Copilot, or Agents skill directories, and makes lady-lens the default for code search (a skill only loads when a task matches it). The rules live in one file, `~/.lady-lens/lens-instructions.md` (from `skills/lady-lens/lens-instructions.md`). Files you own get only one marked line: in `CLAUDE.md` an `@` import of that file, elsewhere the core rule itself plus a link to it: `~/.claude/CLAUDE.md` (an `@` import), `~/.copilot/copilot-instructions.md`, `~/.codex/AGENTS.md` and `~/.vibe/AGENTS.md` (Mistral Vibe). VS Code (`User/prompts/lady-lens.instructions.md`) and Antigravity (`~/.gemini/config/rules/lady-lens.md`) get a rules file of their own. `lens uninstall --skill` removes the skill, that one line and those two files; nothing else in your files changes.
|
|
169
|
+
|
|
170
|
+
Start the background service:
|
|
171
|
+
```bash
|
|
172
|
+
lens mcp -d # starts Streamable HTTP MCP on http://127.0.0.1:4318/mcp and UI on http://127.0.0.1:4317
|
|
173
|
+
lens stop # stops the background services
|
|
174
|
+
lens stop <pid> # stops one tracked process
|
|
175
|
+
lens ps # lists the tracked daemon PIDs per folder
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
### One daemon, many projects
|
|
179
|
+
One daemon serves every registered project (`lens add <dir>`). Pick the project per client by putting it in the URL:
|
|
180
|
+
|
|
181
|
+
```json
|
|
182
|
+
{ "mcpServers": { "lady-lens": { "url": "http://127.0.0.1:4318/mcp?repo=C:/git/my-project" } } }
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
`repo` is a registered folder or id (the `X-Lens-Repo` header works too). An unregistered repo is refused (HTTP 403). Without it, the folder `lens mcp -d` was started in is used, and a tool call can still override it with its own `repo` argument. Tool calls are serialized, so simultaneous requests for different projects do not mix.
|
|
186
|
+
|
|
187
|
+
The UI dashboard started by `lens mcp -d` follows the same rule: `http://127.0.0.1:4317/?repo=<folder|id>` shows that project (unregistered: HTTP 403), and a dropdown appears when more than one project is registered.
|
|
188
|
+
|
|
189
|
+
### 1. Streamable HTTP Mode (Recommended)
|
|
190
|
+
When running `lens mcp -d`, add this to your MCP client configuration:
|
|
191
|
+
|
|
192
|
+
```json
|
|
193
|
+
{
|
|
194
|
+
"mcpServers": {
|
|
195
|
+
"lady-lens": {
|
|
196
|
+
"url": "http://127.0.0.1:4318/mcp"
|
|
197
|
+
}
|
|
198
|
+
}
|
|
199
|
+
}
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
The legacy SSE endpoint remains available at `http://127.0.0.1:4318/sse` for older clients.
|
|
203
|
+
|
|
204
|
+
Config/project files are available through MCP without extra repository configuration:
|
|
205
|
+
|
|
206
|
+
```json
|
|
207
|
+
{ "name": "config_grep", "arguments": { "pattern": "PackageReference|ProjectReference" } }
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
`config_update` accepts the complete new file content. Read the file first, then pass its SHA-256 as `expectedHash` to reject stale edits:
|
|
211
|
+
|
|
212
|
+
```json
|
|
213
|
+
{
|
|
214
|
+
"name": "config_update",
|
|
215
|
+
"arguments": {
|
|
216
|
+
"path": "App/App.csproj",
|
|
217
|
+
"content": "<Project>...</Project>",
|
|
218
|
+
"expectedHash": "<sha256-of-read-content>"
|
|
219
|
+
}
|
|
220
|
+
}
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
The update is limited to repository config files and refreshes graph dependencies automatically.
|
|
224
|
+
|
|
225
|
+
### 2. Direct Stdio Mode
|
|
226
|
+
If you prefer the agent to spawn lady-lens directly on demand:
|
|
227
|
+
|
|
228
|
+
```json
|
|
229
|
+
{
|
|
230
|
+
"mcpServers": {
|
|
231
|
+
"lady-lens": {
|
|
232
|
+
"command": "node",
|
|
233
|
+
"args": ["C:/git/lady-lens/bin/lens.mjs", "mcp", "--stdio"]
|
|
234
|
+
}
|
|
235
|
+
}
|
|
236
|
+
}
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
### Client Config Locations:
|
|
240
|
+
- **Google Antigravity**: `%USERPROFILE%\.gemini\antigravity\mcp_config.json`
|
|
241
|
+
- **Antigravity CLI**: `%USERPROFILE%\.gemini\config\mcp_config.json`. It takes stdio or Streamable HTTP (`/mcp`) only; an `/sse` url does not work there. `lens install antigravity-cli` writes a stdio entry: no daemon, no port, and no loopback call that the agent's sandbox might block.
|
|
242
|
+
- **Gemini CLI**: `%USERPROFILE%\.gemini\settings.json`
|
|
243
|
+
- **Claude Code**: `%USERPROFILE%\.claude.json`
|
|
244
|
+
- **Windsurf**: `%USERPROFILE%\.codeium\windsurf\mcp_config.json`
|
|
245
|
+
- **Codex**: `%USERPROFILE%\.codex\config.toml` (`[mcp_servers.lady-lens]`)
|
|
246
|
+
- **Mistral Vibe**: `%USERPROFILE%\.vibe\config.toml` (`[[mcp_servers]]` with `name = "lady-lens"`)
|
|
247
|
+
- **VS Code**: `%APPDATA%\Code\User\mcp.json` (key `servers`)
|
|
248
|
+
- **Claude Desktop**: `%APPDATA%\Claude\claude_desktop_config.json`
|
|
249
|
+
- **Cursor**: `Settings -> Cursor Settings -> MCP -> Add new MCP server`
|
|
250
|
+
- **VS Code (Cline / Roo Code)**: Settings -> MCP Servers
|
|
251
|
+
|
|
252
|
+
In the two TOML files `lens install` appends a block whose every line ends in `# lady-lens:mcp`; `lens uninstall` removes exactly those lines. An entry you wrote by hand is left alone.
|
|
253
|
+
|
|
254
|
+
## Where the data lives
|
|
255
|
+
|
|
256
|
+
One Ladybug database per repository in `~/.lady-lens/repos/<id>/graph.lbdb` (`<id>` = a short hash of the repo path), and a list of every repo in `~/.lady-lens/repos.json`. Nothing is written into the repository itself.
|
|
257
|
+
|
|
258
|
+
What is indexed: source files of every language lens parses (JavaScript, TypeScript, C#, Python, Java, Go, Rust, PHP, Ruby, Kotlin, Swift, C and C++), `.md`, `.sql`, `.ps1` and configuration (`.json`, `.yaml`, `.csproj`, `.sln`), minus `node_modules`, `.git`, `outputs`, `coverage`, `dist`, `build`, `bin`, `obj` and a few more. A repository describes its own in `.lady-lens.yaml` (`project.exclude_dirs`, `project.graph_extensions`). What `.gitignore` leaves out is not indexed either: git says what it ignores, and in a folder git refuses ("dubious ownership") or without git lens reads the `.gitignore` files itself.
|
|
259
|
+
|
|
260
|
+
Node.js `>=18` is required. Mendix `.mpr` projects are handled through the `mxcli` contributor when `mxcli` is available.
|
|
261
|
+
|
|
262
|
+
Decisions: in a `besluiten.md`, every `- **Title**: text` under a `## YYYY-MM-DD` heading is a decision node; `(vervangt: <old title>)` supersedes an older one, which is then only shown with `history: true`.
|
|
263
|
+
|
|
264
|
+
## Evals
|
|
265
|
+
|
|
266
|
+
`npm run eval:graph` syncs a frozen mini-repo and lady-lens itself into a temporary database and asks `graph_query` the hand-checked questions in `core/eval/fixtureGold.json` and `evals/graph-gold.json`: recall@5, MRR, negatives that must stay empty, and freshness after add/change/remove. It is also part of `npm test`.
|
|
267
|
+
|
|
268
|
+
A host evaluates its own repository with the same functions:
|
|
269
|
+
|
|
270
|
+
```js
|
|
271
|
+
import { runGraphEval, formatGraphEval, scoreAnswer, summarize } from 'lady-lens/eval';
|
|
272
|
+
|
|
273
|
+
const report = await runGraphEval({ repo: { root, queries, settings }, thresholds }); // queries: { id, query, expected: [paths] }
|
|
274
|
+
console.log(formatGraphEval(report));
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
`scoreAnswer` and `summarize` score a search bench: an answer text against expected and forbidden paths, with precision, characters per correct item and richness.
|
|
278
|
+
|
|
279
|
+
## Performance
|
|
280
|
+
|
|
281
|
+
Measure first, then optimize: an optimization without numbers before and after is a guess.
|
|
282
|
+
|
|
283
|
+
```
|
|
284
|
+
npm run bench # lady-lens itself, in a temporary database
|
|
285
|
+
npm run bench -- --baseline # ... and keep it as outputs/bench/baseline.json
|
|
286
|
+
npm run bench:compare # the newest run against the baseline: more than 25% slower is a REGRESSION
|
|
287
|
+
npm run bench -- --scale many-imports # a generated repository: default, small-files, large-files, mixed-languages, many-imports (--count, --seed)
|
|
288
|
+
lens bench --repo C:\git\my-project # your own repository: temporary database, the registry stays as it is (lens bench compare)
|
|
289
|
+
LENS_PROFILE=1 lens sync # the phases of one real sync, on stderr
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
Traces: `LENS_TRACE_FILE=<file>` writes one JSON line per span (`trace_id`, `span_id`, `parent_span_id`, `name`, `duration_ms`, `status`, `attributes`), the same shape as Kura's `outputs/traces.jsonl`. A CLI command is the root span (with `node.startup_ms`: Node plus the static imports); below it `load modules`, `tool: <name>`, `freshness: status` and `freshness: sync`, `query: load graph` and every step of a sync. In the daemon each tool call is its own trace. A caller that sets `TRACEPARENT` (W3C, `00-<trace id>-<span id>-01`) gets lens's spans in its own trace; point `LENS_TRACE_FILE` at the caller's file to see them together.
|
|
293
|
+
|
|
294
|
+
```
|
|
295
|
+
$env:LENS_TRACE_FILE = "$HOME\.lady-lens\logs\traces.jsonl"; lens ask graph_query '{"query":"queue"}'
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
Every measurement runs once to warm up and then 5 times (`--runs`). The run shows the median, min, max and the spread, and marks a measurement whose runs differ more than 10% as `unstable`. A full or incremental sync is split into its phases: stored files, scan (with read and hash), parse (per file type), contributors, Mendix, co-change from git, derive relations, write to the graph, record head. `process: lens ask` and `process: daemon start` time a new process from start to answer. Each run is saved as `outputs/bench/<date>-<commit>.json` (for `lens bench`: `~/.lady-lens/bench/<repo id>/`), with the numbers, the lady-lens version, Node, OS, CPU and a hash of the machine; no paths or code of the measured repository. A comparison between two machines or two repositories gives a warning.
|
|
299
|
+
|
|
300
|
+
`npm run check` ends with `npm run test:perf`: the performance tests alone (no coverage, no parallel workers, where a time swung 5x), each measurement held to a budget in `test/perf-budgets.json`. The budgets leave 5x room for a slower or busy machine (CI runs the same step), so they catch a large slowdown; a slowdown of 25% shows in `npm run bench:compare` on your own machine. After a speed-up, `npm run bench:ratchet` makes the budgets stricter; it never loosens one.
|
|
301
|
+
|
|
302
|
+
Baseline, lady-lens 1.5.2 (349 files, 350 nodes), 2026-11-12, median of 5 runs on a development machine (Windows, 16 x i7-11850H, Node 24):
|
|
303
|
+
|
|
304
|
+
| Operation | Median |
|
|
305
|
+
| :--- | ---: |
|
|
306
|
+
| Full sync (parse 59%, write to graph 29%) | 3381 ms |
|
|
307
|
+
| Incremental sync (unchanged) | 193 ms |
|
|
308
|
+
| Graph load, cold / warm | 125 / 127 ms |
|
|
309
|
+
| `graph_query` (end to end) | 197 ms |
|
|
310
|
+
| `functionView` / `folderView` | 50 / 148 ms |
|
|
311
|
+
| Direct queries (`definedIn`, `exports`, `imports`, `importedBy`, `exists`) | 26 to 37 ms |
|
|
312
|
+
| `health` | 157 ms |
|
|
313
|
+
| `diff_impact` (all functions of one file changed) | 204 ms |
|
|
314
|
+
| `cross_repo_search` (3 folders) | 74 ms |
|
|
315
|
+
| `hubs` and `bridges` | 17 ms |
|
|
316
|
+
| `rankGraphNodes` | 4.6 ms |
|
|
317
|
+
| `lens ask` as a new process / daemon start | 854 / 677 ms |
|
|
318
|
+
|
|
319
|
+
A generated repository (`npm run bench -- --scale many-imports`: 1000 source files with 12 imports each, plus tests and documents, 1260 files, seed 1), same machine, median of 3 runs: full sync 6255 ms, of which writing to the graph 5222 ms (83%); incremental sync 285 ms; graph load 564 ms; `graph_query` 576 ms; `folderView` 620 ms; `health` 666 ms; `functionView` 57 ms. Writing to the graph is where a large sync spends its time.
|
|
320
|
+
|
|
321
|
+
## Settings & Configuration
|
|
322
|
+
|
|
323
|
+
lady-lens can be configured fully through a **`config.json`** file in the root of your repository (see [DOCUMENTATIE.md](DOCUMENTATIE.md#3-configuration-through-configjson) for all options):
|
|
324
|
+
|
|
325
|
+
```json
|
|
326
|
+
{
|
|
327
|
+
"project": {
|
|
328
|
+
"graph_roots": ["."],
|
|
329
|
+
"exclude_dirs": [".git", "node_modules", "dist", "build", "outputs", "coverage"],
|
|
330
|
+
"graph_extensions": [".js", ".mjs", ".ts", ".cs", ".md", ".json"]
|
|
331
|
+
},
|
|
332
|
+
"graph": {
|
|
333
|
+
"ast": { "enabled": false },
|
|
334
|
+
"documentation": { "enabled": true }
|
|
335
|
+
},
|
|
336
|
+
"mcp": {
|
|
337
|
+
"port": 4318,
|
|
338
|
+
"uiPort": 4317
|
|
339
|
+
},
|
|
340
|
+
"env": {
|
|
341
|
+
"TOOL_RESULT_CHARS": "6000",
|
|
342
|
+
"DEBUG_LEVEL": "2"
|
|
343
|
+
}
|
|
344
|
+
}
|
|
345
|
+
```
|
|
346
|
+
|
|
347
|
+
Settings can also be overridden with the environment variables `LENS_<NAME>`: `LENS_GRAPH_DB`, `LENS_REPO_ROOT`, `LENS_SETTINGS_PATH`, `LENS_TOOL_RESULT_CHARS`, `LENS_READ_CHUNK_MAX_CHARS`, `LENS_READ_CHUNK_MAX_LINES`, `LENS_GREP_MAX_MATCHES`, `LENS_DEBUG_LOG_FILE`, `LENS_DEBUG_LEVEL`, `LENS_MDL_EXPORT` (`background` default, `inline`, `off`: the Mendix MDL export after a model change), `LENS_MXCLI_TIMEOUT_MS` (time limit of one mxcli call, default 120000).
|
|
348
|
+
|
|
349
|
+
## As a library (NPM Package)
|
|
350
|
+
|
|
351
|
+
Every API port is available directly from the package:
|
|
352
|
+
|
|
353
|
+
Repository sync goes through `createGraphSync().sync()`. Use `mode: 'incremental'` for the normal sync or `mode: 'full'` for a complete re-index.
|
|
354
|
+
|
|
355
|
+
```js
|
|
356
|
+
import {
|
|
357
|
+
createGraphSync,
|
|
358
|
+
functionViewTool,
|
|
359
|
+
folderViewTool,
|
|
360
|
+
healthTool,
|
|
361
|
+
definedInTool,
|
|
362
|
+
graph_query,
|
|
363
|
+
grep,
|
|
364
|
+
glob,
|
|
365
|
+
read_chunk,
|
|
366
|
+
RESEARCH_TOOLS,
|
|
367
|
+
configureLensEnv,
|
|
368
|
+
configureLensLog
|
|
369
|
+
} from 'lady-lens';
|
|
370
|
+
|
|
371
|
+
// Run an incremental sync through the public sync API
|
|
372
|
+
const syncResult = await createGraphSync().sync({ mode: 'incremental' });
|
|
373
|
+
|
|
374
|
+
// Ask for function, folder or code health details
|
|
375
|
+
const fn = await functionViewTool({ symbol: 'createGraphSync' });
|
|
376
|
+
const health = await healthTool({ limit: 10 });
|
|
377
|
+
```
|
|
378
|
+
|
|
379
|
+
Specific subpath imports (`lady-lens/graph`, `lady-lens/search`, `lady-lens/tools`, `lady-lens/mcp`, `lady-lens/repository`) remain fully supported.
|
|
380
|
+
|
|
381
|
+
## Supported languages
|
|
382
|
+
|
|
383
|
+
For each file lady-lens extracts symbols with line ranges, exports, imports, calls, a purpose line and an estimate of cyclomatic complexity. These feed `definedIn`, `imports`, `importedBy`, `functionView`, `folderView` and `health`.
|
|
384
|
+
|
|
385
|
+
| Kind | Languages and files | How |
|
|
386
|
+
| :--- | :--- | :--- |
|
|
387
|
+
| JavaScript | `.js`, `.mjs`, `.cjs`, `.jsx` | full syntax tree (acorn) |
|
|
388
|
+
| Other code | TypeScript (`.ts`, `.tsx`), C# (`.cs`), Python, Java, Kotlin (`.kt`, `.kts`), Swift, Go, Rust, C and C++ (`.c`, `.cpp`, `.cc`, `.cxx`, `.h`, `.hpp`), PHP, Ruby | pattern-based configuration per language (`core/graph/sync/languages`) |
|
|
389
|
+
| Database and web | SQL, CSS, SCSS, LESS, HTML | pattern-based |
|
|
390
|
+
| Scripts | Bash (`.sh`, `.bash`, `.zsh`), PowerShell (`.ps1`, `.psm1`, `.psd1`), batch (`.bat`, `.cmd`) | pattern-based |
|
|
391
|
+
| Infrastructure | Dockerfile, YAML, TOML, Terraform (`.tf`), `package.json` | pattern-based |
|
|
392
|
+
| Documents | Markdown, text, reStructuredText (`.md`, `.markdown`, `.txt`, `.rst`) | links, mentions and decisions |
|
|
393
|
+
| Project files | `.csproj`, `.sln`, `.props`, `.targets`, `.xml`, `.ini` | file nodes |
|
|
394
|
+
| Mendix | `.mpr` projects, through the `mxcli` contributor when `mxcli` is on the path | project, module, element and page-field nodes (`MendixPageField`, with `metadata.required` from the attribute's `IsRequired`) |
|
|
395
|
+
|
|
396
|
+
Only JavaScript uses a real parser. The pattern-based languages can miss unusual syntax, so treat their call and complexity numbers as estimates. Adding a language means adding one configuration file in `core/graph/sync/languages` and registering it in `index.js`; see the existing ones for the fields.
|
|
397
|
+
|
|
398
|
+
## Develop
|
|
399
|
+
|
|
400
|
+
```
|
|
401
|
+
npm test
|
|
402
|
+
npm run pack # dist/lady-lens-<version>.tgz, to install in another project
|
|
403
|
+
```
|
|
404
|
+
|
|
405
|
+
Not here yet: a real parser for languages other than JavaScript, and framework-specific analysis.
|