@vyuhlabs/dxkit 2.6.0 → 2.7.0

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.
Files changed (151) hide show
  1. package/CHANGELOG.md +54 -13
  2. package/README.md +208 -459
  3. package/dist/analyzers/bom/discovery.d.ts +3 -4
  4. package/dist/analyzers/bom/discovery.d.ts.map +1 -1
  5. package/dist/analyzers/bom/discovery.js +3 -4
  6. package/dist/analyzers/bom/discovery.js.map +1 -1
  7. package/dist/analyzers/bom/types.d.ts +1 -1
  8. package/dist/analyzers/dashboard/index.d.ts.map +1 -1
  9. package/dist/analyzers/dashboard/index.js +42 -5
  10. package/dist/analyzers/dashboard/index.js.map +1 -1
  11. package/dist/analyzers/quality/detailed.d.ts +8 -1
  12. package/dist/analyzers/quality/detailed.d.ts.map +1 -1
  13. package/dist/analyzers/quality/detailed.js +43 -10
  14. package/dist/analyzers/quality/detailed.js.map +1 -1
  15. package/dist/analyzers/security/detailed.d.ts +8 -1
  16. package/dist/analyzers/security/detailed.d.ts.map +1 -1
  17. package/dist/analyzers/security/detailed.js +14 -1
  18. package/dist/analyzers/security/detailed.js.map +1 -1
  19. package/dist/analyzers/tests/detailed.d.ts +8 -1
  20. package/dist/analyzers/tests/detailed.d.ts.map +1 -1
  21. package/dist/analyzers/tests/detailed.js +26 -7
  22. package/dist/analyzers/tests/detailed.js.map +1 -1
  23. package/dist/analyzers/tools/cloc.js +3 -3
  24. package/dist/analyzers/tools/cloc.js.map +1 -1
  25. package/dist/analyzers/tools/exclusions.d.ts +12 -12
  26. package/dist/analyzers/tools/exclusions.d.ts.map +1 -1
  27. package/dist/analyzers/tools/exclusions.js +27 -13
  28. package/dist/analyzers/tools/exclusions.js.map +1 -1
  29. package/dist/analyzers/tools/graphify.d.ts +39 -5
  30. package/dist/analyzers/tools/graphify.d.ts.map +1 -1
  31. package/dist/analyzers/tools/graphify.js +609 -45
  32. package/dist/analyzers/tools/graphify.js.map +1 -1
  33. package/dist/analyzers/tools/nuget-package-reference.d.ts +4 -4
  34. package/dist/analyzers/tools/nuget-package-reference.js +4 -4
  35. package/dist/analyzers/tools/osv-scanner-fix.d.ts +4 -5
  36. package/dist/analyzers/tools/osv-scanner-fix.d.ts.map +1 -1
  37. package/dist/analyzers/tools/osv-scanner-fix.js +4 -5
  38. package/dist/analyzers/tools/osv-scanner-fix.js.map +1 -1
  39. package/dist/analyzers/tools/parallel.d.ts.map +1 -1
  40. package/dist/analyzers/tools/parallel.js +7 -0
  41. package/dist/analyzers/tools/parallel.js.map +1 -1
  42. package/dist/analyzers/tools/vendored-advisor.d.ts.map +1 -1
  43. package/dist/analyzers/tools/vendored-advisor.js +3 -4
  44. package/dist/analyzers/tools/vendored-advisor.js.map +1 -1
  45. package/dist/analyzers/xlsx/licenses.d.ts +7 -7
  46. package/dist/analyzers/xlsx/licenses.js +7 -7
  47. package/dist/cli.d.ts.map +1 -1
  48. package/dist/cli.js +80 -3
  49. package/dist/cli.js.map +1 -1
  50. package/dist/dashboard/graph-adapter.d.ts +151 -0
  51. package/dist/dashboard/graph-adapter.d.ts.map +1 -0
  52. package/dist/dashboard/graph-adapter.js +415 -0
  53. package/dist/dashboard/graph-adapter.js.map +1 -0
  54. package/dist/dashboard/graph-tab.d.ts +109 -0
  55. package/dist/dashboard/graph-tab.d.ts.map +1 -0
  56. package/dist/dashboard/graph-tab.js +297 -0
  57. package/dist/dashboard/graph-tab.js.map +1 -0
  58. package/dist/dashboard/vendor/vis-network.min.js +34 -0
  59. package/dist/explore/cli/api-surface.d.ts +12 -0
  60. package/dist/explore/cli/api-surface.d.ts.map +1 -0
  61. package/dist/explore/cli/api-surface.js +57 -0
  62. package/dist/explore/cli/api-surface.js.map +1 -0
  63. package/dist/explore/cli/communities.d.ts +10 -0
  64. package/dist/explore/cli/communities.d.ts.map +1 -0
  65. package/dist/explore/cli/communities.js +47 -0
  66. package/dist/explore/cli/communities.js.map +1 -0
  67. package/dist/explore/cli/context.d.ts +16 -0
  68. package/dist/explore/cli/context.d.ts.map +1 -0
  69. package/dist/explore/cli/context.js +118 -0
  70. package/dist/explore/cli/context.js.map +1 -0
  71. package/dist/explore/cli/entry-points.d.ts +12 -0
  72. package/dist/explore/cli/entry-points.d.ts.map +1 -0
  73. package/dist/explore/cli/entry-points.js +85 -0
  74. package/dist/explore/cli/entry-points.js.map +1 -0
  75. package/dist/explore/cli/feature.d.ts +16 -0
  76. package/dist/explore/cli/feature.d.ts.map +1 -0
  77. package/dist/explore/cli/feature.js +89 -0
  78. package/dist/explore/cli/feature.js.map +1 -0
  79. package/dist/explore/cli/file.d.ts +12 -0
  80. package/dist/explore/cli/file.d.ts.map +1 -0
  81. package/dist/explore/cli/file.js +139 -0
  82. package/dist/explore/cli/file.js.map +1 -0
  83. package/dist/explore/cli/hot-files.d.ts +11 -0
  84. package/dist/explore/cli/hot-files.d.ts.map +1 -0
  85. package/dist/explore/cli/hot-files.js +63 -0
  86. package/dist/explore/cli/hot-files.js.map +1 -0
  87. package/dist/explore/context-hook.d.ts +42 -0
  88. package/dist/explore/context-hook.d.ts.map +1 -0
  89. package/dist/explore/context-hook.js +131 -0
  90. package/dist/explore/context-hook.js.map +1 -0
  91. package/dist/explore/finding-context.d.ts +69 -0
  92. package/dist/explore/finding-context.d.ts.map +1 -0
  93. package/dist/explore/finding-context.js +102 -0
  94. package/dist/explore/finding-context.js.map +1 -0
  95. package/dist/explore/format.d.ts +64 -0
  96. package/dist/explore/format.d.ts.map +1 -0
  97. package/dist/explore/format.js +99 -0
  98. package/dist/explore/format.js.map +1 -0
  99. package/dist/explore/load.d.ts +50 -0
  100. package/dist/explore/load.d.ts.map +1 -0
  101. package/dist/explore/load.js +197 -0
  102. package/dist/explore/load.js.map +1 -0
  103. package/dist/explore/queries.d.ts +413 -0
  104. package/dist/explore/queries.d.ts.map +1 -0
  105. package/dist/explore/queries.js +855 -0
  106. package/dist/explore/queries.js.map +1 -0
  107. package/dist/explore/types.d.ts +130 -0
  108. package/dist/explore/types.d.ts.map +1 -0
  109. package/dist/explore/types.js +28 -0
  110. package/dist/explore/types.js.map +1 -0
  111. package/dist/explore-cli.d.ts +45 -0
  112. package/dist/explore-cli.d.ts.map +1 -0
  113. package/dist/explore-cli.js +213 -0
  114. package/dist/explore-cli.js.map +1 -0
  115. package/dist/generator.d.ts.map +1 -1
  116. package/dist/generator.js +19 -0
  117. package/dist/generator.js.map +1 -1
  118. package/dist/languages/csharp.d.ts.map +1 -1
  119. package/dist/languages/csharp.js +31 -11
  120. package/dist/languages/csharp.js.map +1 -1
  121. package/dist/languages/go.d.ts.map +1 -1
  122. package/dist/languages/go.js +4 -0
  123. package/dist/languages/go.js.map +1 -1
  124. package/dist/languages/index.d.ts +27 -0
  125. package/dist/languages/index.d.ts.map +1 -1
  126. package/dist/languages/index.js +35 -0
  127. package/dist/languages/index.js.map +1 -1
  128. package/dist/languages/java.d.ts.map +1 -1
  129. package/dist/languages/java.js +4 -0
  130. package/dist/languages/java.js.map +1 -1
  131. package/dist/languages/kotlin.d.ts.map +1 -1
  132. package/dist/languages/kotlin.js +4 -0
  133. package/dist/languages/kotlin.js.map +1 -1
  134. package/dist/languages/python.d.ts.map +1 -1
  135. package/dist/languages/python.js +4 -0
  136. package/dist/languages/python.js.map +1 -1
  137. package/dist/languages/ruby.d.ts.map +1 -1
  138. package/dist/languages/ruby.js +4 -0
  139. package/dist/languages/ruby.js.map +1 -1
  140. package/dist/languages/rust.d.ts.map +1 -1
  141. package/dist/languages/rust.js +4 -0
  142. package/dist/languages/rust.js.map +1 -1
  143. package/dist/languages/types.d.ts +54 -0
  144. package/dist/languages/types.d.ts.map +1 -1
  145. package/dist/languages/typescript.d.ts.map +1 -1
  146. package/dist/languages/typescript.js +5 -1
  147. package/dist/languages/typescript.js.map +1 -1
  148. package/package.json +2 -1
  149. package/templates/.claude/skills/dxkit-action/SKILL.md +21 -1
  150. package/templates/.claude/skills/dxkit-reports/SKILL.md +3 -1
  151. package/templates/AGENTS.md.template +8 -1
@@ -0,0 +1,413 @@
1
+ /**
2
+ * Canonical graph query module. Per CLAUDE.md Rule 12, every consumer
3
+ * (explore CLI subcommands, dashboard viz adapter, future 2.8 context
4
+ * CLI, future 2.8 reachability) imports from here — never reimplements
5
+ * graph traversal. Arch-check enforces.
6
+ *
7
+ * Sprint 1 ships the SKELETON: type signatures + empty implementations
8
+ * so the canonical entry points exist for the arch rule to lock onto.
9
+ * Sprint 2 fills the bodies as the explore CLI subcommands land.
10
+ *
11
+ * Every query is a pure function: takes a `Graph` (and optionally
12
+ * other args), returns a typed result. No side effects, no I/O,
13
+ * no caching — caching belongs at the loader level, not the query
14
+ * level.
15
+ */
16
+ import type { DetectedStack } from '../types';
17
+ import type { Graph, GraphNode } from './types';
18
+ /** Nodes that call into the given nodeId (predecessors via `calls` edges). */
19
+ export declare function callersOf(graph: Graph, nodeId: string): GraphNode[];
20
+ /** Nodes that the given nodeId calls into (successors via `calls` edges). */
21
+ export declare function calleesOf(graph: Graph, nodeId: string): GraphNode[];
22
+ /** All nodes declared in the given source file. */
23
+ export declare function nodesInFile(graph: Graph, sourceFile: string): GraphNode[];
24
+ /**
25
+ * One row of `vyuh-dxkit explore hot-files` output. A "hot" file is
26
+ * one many other files depend on (high total in-degree across all the
27
+ * symbols it declares + inbound imports to the file's module node).
28
+ *
29
+ * - `callsIn`: count of `calls` edges terminating at any symbol in
30
+ * the file (summed across the file's function / class / method
31
+ * nodes)
32
+ * - `importsIn`: count of `imports_from` edges terminating at the
33
+ * file's module node
34
+ * - `callsOut`: count of `calls` edges originating from any symbol
35
+ * in the file
36
+ * - `communityId` / `communityLabel`: the community the file's
37
+ * module node belongs to, when one exists; label is the
38
+ * community's dominantSourceDir for a quick visual anchor
39
+ */
40
+ export interface HotFileResult {
41
+ sourceFile: string;
42
+ callsIn: number;
43
+ importsIn: number;
44
+ callsOut: number;
45
+ communityId?: number;
46
+ communityLabel?: string;
47
+ }
48
+ /**
49
+ * Top-N files by total in-degree (callers + importers). The
50
+ * "centrality" proxy — files many other files depend on. Useful as
51
+ * a "what's the foundational layer of this repo?" answer.
52
+ *
53
+ * Files are derived from the union of `sourceFile` across all nodes;
54
+ * the per-file aggregation traverses each node's inbound/outbound
55
+ * edges. Limit defaults to 20 per the Sprint 0 spec.
56
+ */
57
+ export declare function hotFilesQuery(graph: Graph, limit?: number): HotFileResult[];
58
+ /**
59
+ * One row of `vyuh-dxkit explore communities` output. A community is
60
+ * a Louvain-clustered grouping of nodes; the dominant source dir +
61
+ * pack give the reader a visual anchor ("this is the auth stuff" /
62
+ * "this is the bom layer").
63
+ */
64
+ export interface CommunityResult {
65
+ id: number;
66
+ nodeCount: number;
67
+ dominantSourceDir: string;
68
+ dominantPack: string;
69
+ cohesion: number;
70
+ topHotFiles: string[];
71
+ }
72
+ /**
73
+ * Top-N communities by node count, with each community's top-3 hot
74
+ * files (by in-degree within the community). Gives a "what are the
75
+ * natural modules in this repo?" answer that complements `hot-files`
76
+ * (which is global).
77
+ */
78
+ export declare function communitiesQuery(graph: Graph, limit?: number): CommunityResult[];
79
+ /**
80
+ * One-symbol entry inside a file summary — a function / class /
81
+ * method declared in the file plus its in/out call counts. Used by
82
+ * the `explore file <path>` subcommand to show "here's what this
83
+ * file declares + how it interconnects."
84
+ */
85
+ export interface FileSymbolSummary {
86
+ id: string;
87
+ kind: 'function' | 'class' | 'method' | 'module';
88
+ label: string;
89
+ line?: number;
90
+ exported?: boolean;
91
+ callsIn: number;
92
+ callsOut: number;
93
+ }
94
+ /**
95
+ * Full summary for a single file: its symbols, its callers (deduped
96
+ * to unique files for readability), its callees, its inbound and
97
+ * outbound imports, and its community membership. Used by `explore
98
+ * file <path>`.
99
+ *
100
+ * `callerFiles` / `calleeFiles` are deduped at the FILE level — if
101
+ * 12 symbols from src/foo.ts call into this file's symbols, the
102
+ * caller appears once in `callerFiles` with `count: 12`. The reader
103
+ * usually wants "which files depend on me" not "every individual
104
+ * call site" (which would scroll for pages on hot files).
105
+ */
106
+ export interface FileSummary {
107
+ sourceFile: string;
108
+ found: boolean;
109
+ symbols: FileSymbolSummary[];
110
+ callerFiles: Array<{
111
+ sourceFile: string;
112
+ count: number;
113
+ }>;
114
+ calleeFiles: Array<{
115
+ sourceFile: string;
116
+ count: number;
117
+ }>;
118
+ importsIn: Array<{
119
+ sourceFile: string;
120
+ }>;
121
+ importsOut: Array<{
122
+ sourceFile: string;
123
+ }>;
124
+ communityId?: number;
125
+ communityLabel?: string;
126
+ communityPack?: string;
127
+ }
128
+ /**
129
+ * Build the per-file summary. `found: false` when the file isn't in
130
+ * the graph (excluded by minified detection / vendored / unsupported
131
+ * extension); the consumer handles that case with an explanatory
132
+ * note instead of an empty result.
133
+ */
134
+ export declare function fileSummaryQuery(graph: Graph, sourceFile: string): FileSummary;
135
+ /**
136
+ * One row of `vyuh-dxkit explore entry-points` output. An entry
137
+ * point is a symbol declared in a source file whose path matches
138
+ * one of the active packs' `architecturalShape.primaryComponentPaths`
139
+ * or `routePaths` (per CLAUDE.md Rule 8 — these are pack-driven, no
140
+ * hardcoded framework strings here).
141
+ *
142
+ * `componentType` carries the matched pattern label (e.g. `routes`,
143
+ * `controllers`, `forms`) so the consumer can group by surface.
144
+ * Sourced from the pack's `dominantVocabulary` when available, else
145
+ * from the matched path segment.
146
+ */
147
+ export interface EntryPointResult {
148
+ sourceFile: string;
149
+ line?: number;
150
+ symbol: string;
151
+ componentType: string;
152
+ callsOut: number;
153
+ pack: string;
154
+ }
155
+ /**
156
+ * Discover entry-point symbols by intersecting graph nodes with the
157
+ * union of active packs' `primaryComponentPaths` + `routePaths`. The
158
+ * rank is by call out-degree — entry points typically fan OUT (they
159
+ * receive a request, then call many downstream functions). A high
160
+ * out-degree node in a primary-architecture path is almost certainly
161
+ * a real entry point.
162
+ *
163
+ * `flags` is the per-pack boolean map from `DetectedStack.languages`;
164
+ * only patterns from active packs contribute. This matches the
165
+ * existing pack-driven analyzer pattern.
166
+ */
167
+ export declare function entryPointsQuery(graph: Graph, primaryPaths: ReadonlyArray<string>, routePaths: ReadonlyArray<string>, limit?: number): EntryPointResult[];
168
+ export type LanguageFlags = DetectedStack['languages'];
169
+ /**
170
+ * One row of `vyuh-dxkit explore api-surface` output. An "API surface"
171
+ * symbol is one that the language pack identifies as exported AND has
172
+ * zero internal callers (no other file in the graph calls into it).
173
+ *
174
+ * Typically this set falls into three buckets:
175
+ * - Genuine public API (library entry points, named exports)
176
+ * - CLI entry points (legitimately not internally imported)
177
+ * - Dead exports (false positives surfaced honestly)
178
+ *
179
+ * The consumer should verify before treating any as dead code.
180
+ */
181
+ export interface ApiSurfaceResult {
182
+ sourceFile: string;
183
+ line?: number;
184
+ symbol: string;
185
+ kind: 'function' | 'class' | 'method' | 'module';
186
+ pack: string;
187
+ }
188
+ /**
189
+ * Find exported symbols with zero internal callers. `packsExcluded`
190
+ * lists pack ids whose `exportDetection.reliability === 'unreliable'`
191
+ * — those packs' nodes are skipped because we can't trust their
192
+ * `exported` flag (today: ruby). The consumer surfaces the exclusion
193
+ * as a note in its output.
194
+ */
195
+ export declare function apiSurfaceQuery(graph: Graph, packsExcluded: ReadonlyArray<string>, limit?: number): ApiSurfaceResult[];
196
+ /**
197
+ * Options for `featureQuery`. `substring` enables the noisier
198
+ * keyword-substring expansion (off by default per Sprint 0 spec —
199
+ * false-positive prone for short keywords).
200
+ */
201
+ export interface FeatureQueryOpts {
202
+ substring?: boolean;
203
+ limit?: number;
204
+ }
205
+ /**
206
+ * A clustering of symbols that look like they implement one feature.
207
+ * The community membership is the structural backbone — symbols in
208
+ * the same community are tightly coupled by definition. The role
209
+ * label comes from the community's dominantPack/dominantSourceDir
210
+ * + per-pack vocabulary when available.
211
+ */
212
+ export interface FeatureCluster {
213
+ clusterId: number;
214
+ communityId?: number;
215
+ role: string;
216
+ dominantSourceDir: string;
217
+ files: string[];
218
+ keySymbols: string[];
219
+ seedHits: number;
220
+ }
221
+ /**
222
+ * Full result of a feature query. `results` is non-empty when at
223
+ * least one symbol matched the keyword; `suggestions` is populated
224
+ * only when `results` is empty (edit-distance ≤2 against the
225
+ * symbolIndex keys, top-3). `centralEntryPoint` names the highest
226
+ * call-in-degree node across all clusters when results were found
227
+ * — the natural "if you only look at one file, look here" anchor.
228
+ */
229
+ export interface FeatureResult {
230
+ results: FeatureCluster[];
231
+ suggestions: Array<{
232
+ key: string;
233
+ hits: number;
234
+ }>;
235
+ centralEntryPoint?: {
236
+ sourceFile: string;
237
+ line?: number;
238
+ symbol: string;
239
+ calledFrom: number;
240
+ };
241
+ }
242
+ /**
243
+ * The marquee query — "where is feature X implemented?" Three-stage
244
+ * resolution:
245
+ *
246
+ * 1. Direct symbolIndex lookup (case-insensitive, exact match on
247
+ * the stripped name)
248
+ * 2. Substring expansion (opt-in via opts.substring) — scans every
249
+ * node's label for substring match
250
+ * 3. Structural expansion — for each seed, gather community
251
+ * membership + immediate callers + callees, group by community
252
+ *
253
+ * On zero hits, computes edit-distance suggestions against the
254
+ * symbolIndex keys so the caller can prompt the user with "did you
255
+ * mean..."
256
+ */
257
+ export declare function featureQuery(graph: Graph, keyword: string, opts?: FeatureQueryOpts): FeatureResult;
258
+ /**
259
+ * Options for `contextQuery`. `budget` is the soft token ceiling on
260
+ * the rendered output (BFS stops adding nodes once the running
261
+ * estimate would exceed it). `tokensPerNode` is the per-symbol render
262
+ * cost estimate the budget math uses — tuned to roughly match one
263
+ * markdown line like "- `foo()` src/a.ts:42 (5 in / 3 out)". `maxDepth`
264
+ * is an optional HARD ceiling on BFS hops for power users; default is
265
+ * budget-bounded only (adaptive depth).
266
+ */
267
+ export interface ContextQueryOpts {
268
+ substring?: boolean;
269
+ budget?: number;
270
+ tokensPerNode?: number;
271
+ maxDepth?: number;
272
+ }
273
+ /** One symbol in the budget-bounded selection. */
274
+ export interface ContextNode {
275
+ id: string;
276
+ symbol: string;
277
+ sourceFile: string;
278
+ line?: number;
279
+ kind: GraphNode['kind'];
280
+ /** 0 = seed (matched the query), 1 = direct neighbor, 2 = … */
281
+ hop: number;
282
+ callsIn: number;
283
+ callsOut: number;
284
+ }
285
+ /** Community grouping of the selection, for orientation. */
286
+ export interface ContextCommunityGroup {
287
+ communityId?: number;
288
+ role: string;
289
+ files: string[];
290
+ symbols: string[];
291
+ }
292
+ /**
293
+ * Result of a context query — a slim, ranked, budget-bounded subgraph
294
+ * built for injection into an LLM's context window (or a human's
295
+ * terminal). The formatter (`src/explore/format.ts`) turns this into
296
+ * markdown / JSON; this function owns only the graph work + budget
297
+ * math (Rule 12).
298
+ *
299
+ * `selection` is BFS-ordered: seeds first (hop 0), then their direct
300
+ * neighbors (hop 1), then hop 2, … — so the most relevant symbols
301
+ * survive when the budget truncates the tail. `anchor` is the
302
+ * highest call-in-degree seed ("if you read one thing, read this").
303
+ * `blastRadius` counts unique callers of the SEEDS (the symbols a
304
+ * change would touch). `suggestions` is populated only when nothing
305
+ * matched (the did-you-mean path). `truncated` + `omittedCount`
306
+ * drive the formatter's honest "+N more …" footer.
307
+ */
308
+ export interface ContextResult {
309
+ query: string;
310
+ matched: boolean;
311
+ anchor?: {
312
+ sourceFile: string;
313
+ line?: number;
314
+ symbol: string;
315
+ calledFrom: number;
316
+ };
317
+ selection: ContextNode[];
318
+ byCommunity: ContextCommunityGroup[];
319
+ blastRadius: {
320
+ callers: number;
321
+ callerFiles: number;
322
+ };
323
+ truncated: boolean;
324
+ omittedCount: number;
325
+ estimatedTokens: number;
326
+ budget: number;
327
+ suggestions: Array<{
328
+ key: string;
329
+ hits: number;
330
+ }>;
331
+ }
332
+ /**
333
+ * The marquee token-reduction primitive — "give me just the relevant
334
+ * structural slice for this query." Resolves seeds the same way
335
+ * `featureQuery` does (shared `findSeedIds`), then expands breadth-
336
+ * first through `calls` edges, stopping when the running token
337
+ * estimate fills the budget (or an optional `maxDepth` ceiling is
338
+ * reached). Adaptive depth falls out for free: a hot symbol's
339
+ * immediate neighbors fill the budget at hop 1, while a cold symbol's
340
+ * sparse neighborhood leaves room to reach hop 2+.
341
+ *
342
+ * Pure: no I/O, no formatting. Same `Graph` in → same `ContextResult`
343
+ * out.
344
+ */
345
+ export declare function contextQuery(graph: Graph, keyword: string, opts?: ContextQueryOpts): ContextResult;
346
+ /**
347
+ * Graph context for a single analyzer finding (a security vuln, a
348
+ * test-gap source file, a quality offender) located at `sourceFile`
349
+ * (+ an optional `line`). Built for the enrichment pass that decorates
350
+ * detailed reports: a fixing agent reading a finding sees its
351
+ * structural blast radius + module membership inline, without running
352
+ * the `context` command itself.
353
+ *
354
+ * `found: false` when the file isn't in the graph (excluded as
355
+ * vendored / autogenerated / minified, an unsupported extension, or
356
+ * simply not parsed by graphify). Consumers degrade gracefully —
357
+ * attach nothing.
358
+ *
359
+ * `blastRadius` is FILE-level: unique caller files / caller symbols
360
+ * across every symbol the file declares — the surface a change to this
361
+ * file would touch. File-level is the robust signal; graphify can
362
+ * conflate same-name symbols across files, so per-symbol caller counts
363
+ * are noisier. `enclosingSymbol` is a labeled best-effort for the
364
+ * symbol the finding sits inside.
365
+ */
366
+ export interface FindingContext {
367
+ found: boolean;
368
+ sourceFile: string;
369
+ community?: {
370
+ id?: number;
371
+ role: string;
372
+ };
373
+ blastRadius: {
374
+ callerFiles: number;
375
+ callers: number;
376
+ topCallerFiles: string[];
377
+ };
378
+ /**
379
+ * Trust level of `blastRadius` for this file's language, stamped by
380
+ * the enrichment adapter (not the pure query — `queries.ts` stays
381
+ * independent of the language registry). `'unreliable'` means
382
+ * graphify can't resolve this language's call edges (today: C#
383
+ * cross-assembly `using`), so a 0 here is NOT evidence of "no callers"
384
+ * and the renderer suppresses the number. Absent ⇒ treated as `'full'`.
385
+ */
386
+ callGraphReliability?: 'full' | 'partial' | 'unreliable';
387
+ /**
388
+ * Best-effort symbol the finding sits inside: the declaration
389
+ * nearest at-or-above `line`. Absent when no `line` was given or the
390
+ * file declares no symbol at-or-above the line. Graph nodes carry
391
+ * only a declaration line (no end line), so this is a heuristic — a
392
+ * finding can sit below the last symbol's declaration yet outside it.
393
+ * Labeled as best-effort so consumers report it honestly.
394
+ */
395
+ enclosingSymbol?: {
396
+ symbol: string;
397
+ line?: number;
398
+ };
399
+ }
400
+ /**
401
+ * Graph context for one finding location. Reuses `fileSummaryQuery`
402
+ * for the file-level caller aggregation + community lookup (Rule 2 —
403
+ * one source of truth for "who depends on this file"), then maps an
404
+ * optional `line` to the nearest enclosing declaration.
405
+ *
406
+ * Pure: same `Graph` + location in → same `FindingContext` out. The
407
+ * enrichment adapter (`src/explore/finding-context.ts`) owns the
408
+ * graph load, the per-finding loop, and the dedupe budget.
409
+ */
410
+ export declare function findingContextQuery(graph: Graph, sourceFile: string, line?: number, opts?: {
411
+ topCallerFiles?: number;
412
+ }): FindingContext;
413
+ //# sourceMappingURL=queries.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../src/explore/queries.ts"],"names":[],"mappings":"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"}