devlensio 1.1.1 → 1.4.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.
- package/dist/graph/buildLookup.d.ts +30 -0
- package/dist/graph/buildLookup.js +36 -1
- package/dist/graph/edges/aliasChain.d.ts +7 -0
- package/dist/graph/edges/aliasChain.js +63 -0
- package/dist/graph/edges/aliasResolution.test.d.ts +1 -0
- package/dist/graph/edges/aliasResolution.test.js +351 -0
- package/dist/graph/edges/callEdges.js +178 -18
- package/dist/graph/edges/callEdges.test.js +119 -0
- package/dist/graph/edges/callOrder.test.d.ts +1 -0
- package/dist/graph/edges/callOrder.test.js +227 -0
- package/dist/graph/edges/importEdges.js +124 -0
- package/dist/graph/edges/propEdges.js +6 -1
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -0
- package/dist/parser/callFlow.d.ts +15 -0
- package/dist/parser/callFlow.js +302 -0
- package/dist/parser/callOrder.test.d.ts +1 -0
- package/dist/parser/callOrder.test.js +407 -0
- package/dist/parser/declarationIds.d.ts +23 -0
- package/dist/parser/declarationIds.js +123 -0
- package/dist/parser/exportsMap.js +1 -90
- package/dist/parser/extractors/components.js +18 -28
- package/dist/parser/extractors/functions.d.ts +21 -1
- package/dist/parser/extractors/functions.js +92 -60
- package/dist/parser/extractors/moduleScope.d.ts +8 -0
- package/dist/parser/extractors/moduleScope.js +80 -0
- package/dist/parser/index.js +12 -0
- package/dist/parser/moduleScope.test.d.ts +1 -0
- package/dist/parser/moduleScope.test.js +176 -0
- package/dist/summarizer/index.js +53 -4
- package/dist/summarizer/prompts.js +111 -50
- package/dist/summarizer/prompts.test.d.ts +1 -0
- package/dist/summarizer/prompts.test.js +112 -0
- package/dist/types.d.ts +63 -0
- package/dist/version.d.ts +1 -0
- package/dist/version.js +2 -0
- package/extractors/go/bin/darwin-amd64/devlens_go_extractor +0 -0
- package/extractors/go/bin/darwin-arm64/devlens_go_extractor +0 -0
- package/extractors/go/bin/linux-amd64/devlens_go_extractor +0 -0
- package/extractors/go/bin/linux-arm64/devlens_go_extractor +0 -0
- package/extractors/go/bin/windows-amd64/devlens_go_extractor.exe +0 -0
- package/extractors/go/calls.go +131 -10
- package/extractors/go/nodes.go +29 -11
- package/extractors/go/parser.go +376 -41
- package/extractors/java/devlens_java_extractor.jar +0 -0
- package/extractors/java/src/devlens/extractor/Extractor.java +52 -12
- package/extractors/java/src/devlens/extractor/LookupMaps.java +2 -0
- package/extractors/java/src/devlens/extractor/Parser.java +420 -1
- package/extractors/java/src/devlens/extractor/edges/Calls.java +105 -5
- package/extractors/python/devlens_extractors_python/edges/calls.py +199 -36
- package/extractors/python/devlens_extractors_python/edges/imports.py +21 -1
- package/extractors/python/devlens_extractors_python/lookup.py +9 -0
- package/extractors/python/devlens_extractors_python/parser/__init__.py +11 -1
- package/extractors/python/devlens_extractors_python/parser/functions.py +199 -42
- package/extractors/rust/bin/darwin-amd64/devlens_rust_extractor +0 -0
- package/extractors/rust/bin/darwin-arm64/devlens_rust_extractor +0 -0
- package/extractors/rust/bin/linux-amd64/devlens_rust_extractor +0 -0
- package/extractors/rust/bin/linux-arm64/devlens_rust_extractor +0 -0
- package/extractors/rust/bin/windows-amd64/devlens_rust_extractor.exe +0 -0
- package/extractors/rust/src/calls.rs +114 -8
- package/extractors/rust/src/lookup.rs +66 -0
- package/extractors/rust/src/nodes.rs +29 -0
- package/extractors/rust/src/parser.rs +362 -27
- package/package.json +77 -73
package/dist/summarizer/index.js
CHANGED
|
@@ -36,6 +36,29 @@ import { createLLMClient } from "./providers/index.js";
|
|
|
36
36
|
import { exceedsThreshold, mapreduceSummarize } from "./mapreduce.js";
|
|
37
37
|
import { withRetry } from "./retry.js";
|
|
38
38
|
import { MAX_GROUP_SUMMARY_SIZE } from "./types.js";
|
|
39
|
+
// ─── LLM concurrency ──────────────────────────────────────────────────────────
|
|
40
|
+
//
|
|
41
|
+
// A topological level can hold hundreds of nodes and each one is an independent
|
|
42
|
+
// LLM request. Firing the whole level at once hammers the provider and gets 429s
|
|
43
|
+
// on every call (measured: 2400+ retries, zero completions on a 3.2k-node repo),
|
|
44
|
+
// so requests are bounded here rather than in the provider. Env-tunable because
|
|
45
|
+
// providers differ; the default is conservative.
|
|
46
|
+
const LLM_CONCURRENCY = (() => {
|
|
47
|
+
const raw = Number(process.env.DEVLENS_LLM_CONCURRENCY ?? "");
|
|
48
|
+
return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 24;
|
|
49
|
+
})();
|
|
50
|
+
async function mapLimited(items, fn) {
|
|
51
|
+
let next = 0;
|
|
52
|
+
const workers = Array.from({ length: Math.min(LLM_CONCURRENCY, items.length) }, async () => {
|
|
53
|
+
for (;;) {
|
|
54
|
+
const i = next++;
|
|
55
|
+
if (i >= items.length)
|
|
56
|
+
return;
|
|
57
|
+
await fn(items[i]);
|
|
58
|
+
}
|
|
59
|
+
});
|
|
60
|
+
await Promise.all(workers);
|
|
61
|
+
}
|
|
39
62
|
// ─── runSummarization ─────────────────────────────────────────────────────────
|
|
40
63
|
//
|
|
41
64
|
// Main entry point — called by runner.ts after Phase 1 completes.
|
|
@@ -109,6 +132,14 @@ export async function runSummarization(input) {
|
|
|
109
132
|
return;
|
|
110
133
|
}
|
|
111
134
|
// ── Step 5: Build or load checkpoint ──────────────────────────────────────
|
|
135
|
+
//
|
|
136
|
+
// forceSummarize means "from scratch": the caller already dropped every summary
|
|
137
|
+
// for this commit, so a checkpoint from an interrupted run is stale state that
|
|
138
|
+
// describes work which no longer exists. Resuming into it marks those levels
|
|
139
|
+
// complete with nothing written behind them, and the run then reports 100% while
|
|
140
|
+
// most nodes stay unsummarized (measured: 791/3217 on a 3.2k-node repo).
|
|
141
|
+
if (job.forceSummarize)
|
|
142
|
+
deleteCheckpoint(graphId, commitHash);
|
|
112
143
|
let checkpoint = loadCheckpoint(graphId, commitHash);
|
|
113
144
|
const isResume = !!checkpoint;
|
|
114
145
|
if (!checkpoint) {
|
|
@@ -159,6 +190,18 @@ export async function runSummarization(input) {
|
|
|
159
190
|
node.summarizedAt = new Date().toISOString();
|
|
160
191
|
}
|
|
161
192
|
// ── Helper: save a batch of node updates to disk ──────────────────────────
|
|
193
|
+
// Partial flush: a single level can hold thousands of nodes (measured: 2612 on a
|
|
194
|
+
// 3.2k-node repo), and saveBatch only runs once the whole level finishes — so a
|
|
195
|
+
// crash or cancel mid-level wrote nothing. This flushes the nodes that already
|
|
196
|
+
// have summaries, which is idempotent because saveNodeSummaries is an upsert.
|
|
197
|
+
const SAVE_EVERY = 200;
|
|
198
|
+
function savePartial(nodes) {
|
|
199
|
+
const done = nodes.filter(n => n.technicalSummary);
|
|
200
|
+
if (done.length === 0)
|
|
201
|
+
return;
|
|
202
|
+
saveBatch(done);
|
|
203
|
+
console.log(`💾 Partial flush — ${done.length}/${nodes.length} nodes of this level saved`);
|
|
204
|
+
}
|
|
162
205
|
function saveBatch(nodes) {
|
|
163
206
|
const updates = new Map(nodes.map(n => [n.id, {
|
|
164
207
|
technicalSummary: n.technicalSummary,
|
|
@@ -192,8 +235,14 @@ export async function runSummarization(input) {
|
|
|
192
235
|
const nodes = level.map(id => allNodesMap.get(id)).filter(Boolean);
|
|
193
236
|
const newInLevel = nodes.filter(n => !n.technicalSummary).length;
|
|
194
237
|
console.log(`🔍 Level ${lvl}: ${nodes.length} nodes, ${newInLevel} new to summarize (skipped ${nodes.length - newInLevel})`);
|
|
195
|
-
//
|
|
196
|
-
|
|
238
|
+
// The whole level is independent, but the request count is bounded, and the
|
|
239
|
+
// completed prefix is flushed periodically so a crash cannot lose the level.
|
|
240
|
+
let flushed = 0;
|
|
241
|
+
await mapLimited(nodes, async (n) => {
|
|
242
|
+
await summarizeNode(n);
|
|
243
|
+
if (++flushed % SAVE_EVERY === 0)
|
|
244
|
+
savePartial(nodes);
|
|
245
|
+
});
|
|
197
246
|
saveBatch(nodes);
|
|
198
247
|
markLevelCompleted(checkpoint, lvl);
|
|
199
248
|
saveCheckpoint(checkpoint);
|
|
@@ -230,7 +279,7 @@ export async function runSummarization(input) {
|
|
|
230
279
|
}
|
|
231
280
|
else {
|
|
232
281
|
// Large cycle — summarize individually
|
|
233
|
-
await
|
|
282
|
+
await mapLimited(nodes, summarizeNode);
|
|
234
283
|
}
|
|
235
284
|
saveBatch(nodes);
|
|
236
285
|
markCycleGroupCompleted(checkpoint, gi);
|
|
@@ -257,7 +306,7 @@ export async function runSummarization(input) {
|
|
|
257
306
|
//Debug-Log
|
|
258
307
|
const newInBatch = batchNodes.filter(n => !n.technicalSummary).length;
|
|
259
308
|
console.log(`🔍 File batch ${fi}-${batchEnd}: ${batchNodes.length} nodes, ${newInBatch} new to summarize (skipped ${batchNodes.length - newInBatch})`);
|
|
260
|
-
await
|
|
309
|
+
await mapLimited(batchNodes, summarizeNode);
|
|
261
310
|
saveBatch(batchNodes);
|
|
262
311
|
markFileNodeBatchCompleted(checkpoint, batchEnd, batchNodes.length);
|
|
263
312
|
saveCheckpoint(checkpoint);
|
|
@@ -28,53 +28,70 @@ export function buildRouteIndex(routes) {
|
|
|
28
28
|
//
|
|
29
29
|
// Built once per summarization run — same for every node.
|
|
30
30
|
// Fingerprint gives the LLM project-level context for better business summaries.
|
|
31
|
-
const BASE_SYSTEM_PROMPT = `You are a senior software engineer analyzing a codebase.
|
|
32
|
-
Your job is to summarize a single code node based on its source code and context.
|
|
33
|
-
|
|
34
|
-
Respond ONLY in this exact XML format — no preamble, no explanation outside the tags:
|
|
35
|
-
|
|
36
|
-
<technical>
|
|
37
|
-
HTML content describing what this code does: its inputs, outputs, side effects, and key logic.
|
|
38
|
-
</technical>
|
|
39
|
-
<business>
|
|
40
|
-
HTML content describing what problem this solves in the product and what feature or domain it belongs to.
|
|
41
|
-
</business>
|
|
42
|
-
<security_severity>none|low|medium|high</security_severity>
|
|
43
|
-
<security_summary>
|
|
44
|
-
HTML content describing the vulnerability (if severity is not none): what data is at risk and how it could be exploited.
|
|
45
|
-
Leave empty if severity is none.
|
|
46
|
-
</security_summary>
|
|
47
|
-
|
|
48
|
-
## Formatting rules for content inside the XML tags
|
|
49
|
-
Use HTML markup — the output is rendered in a browser tooltip, sidebar panel, and detail panel. Follow these conventions:
|
|
50
|
-
|
|
51
|
-
- Inline code, function names, variable names, parameter names, file paths:
|
|
52
|
-
<code>functionName()</code> or <code>someVariable</code>
|
|
53
|
-
- Multi-line code blocks (more than one line of code):
|
|
54
|
-
<pre><code>const x = 1;\nreturn x;</code></pre>
|
|
55
|
-
- Key points / bullet lists (preferred for 3+ items):
|
|
56
|
-
<ul><li>First point.</li><li>Second point.</li></ul>
|
|
57
|
-
- Numbered steps (only when order matters):
|
|
58
|
-
<ol><li>Step one.</li><li>Step two.</li></ol>
|
|
59
|
-
- Bold for important terms or labels: <strong>important</strong>
|
|
60
|
-
- No <h1>/<h2> headings — use <strong> inline labels instead.
|
|
61
|
-
- No inline styles. No <div> wrappers. No Markdown (no **, no backticks, no #).
|
|
62
|
-
- Write in plain prose sentences; use lists only when there are three or more distinct items.
|
|
63
|
-
- Keep paragraphs short — summaries are displayed in compact UI containers (200-300px wide).
|
|
64
|
-
- Avoid long paragraphs; break complex ideas into <ul> lists for scanability.
|
|
65
|
-
|
|
66
|
-
##
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
31
|
+
const BASE_SYSTEM_PROMPT = `You are a senior software engineer analyzing a codebase.
|
|
32
|
+
Your job is to summarize a single code node based on its source code and context.
|
|
33
|
+
|
|
34
|
+
Respond ONLY in this exact XML format — no preamble, no explanation outside the tags:
|
|
35
|
+
|
|
36
|
+
<technical>
|
|
37
|
+
HTML content describing what this code does: its inputs, outputs, side effects, and key logic.
|
|
38
|
+
</technical>
|
|
39
|
+
<business>
|
|
40
|
+
HTML content describing what problem this solves in the product and what feature or domain it belongs to.
|
|
41
|
+
</business>
|
|
42
|
+
<security_severity>none|low|medium|high</security_severity>
|
|
43
|
+
<security_summary>
|
|
44
|
+
HTML content describing the vulnerability (if severity is not none): what data is at risk and how it could be exploited.
|
|
45
|
+
Leave empty if severity is none.
|
|
46
|
+
</security_summary>
|
|
47
|
+
|
|
48
|
+
## Formatting rules for content inside the XML tags
|
|
49
|
+
Use HTML markup — the output is rendered in a browser tooltip, sidebar panel, and detail panel. Follow these conventions:
|
|
50
|
+
|
|
51
|
+
- Inline code, function names, variable names, parameter names, file paths:
|
|
52
|
+
<code>functionName()</code> or <code>someVariable</code>
|
|
53
|
+
- Multi-line code blocks (more than one line of code):
|
|
54
|
+
<pre><code>const x = 1;\nreturn x;</code></pre>
|
|
55
|
+
- Key points / bullet lists (preferred for 3+ items):
|
|
56
|
+
<ul><li>First point.</li><li>Second point.</li></ul>
|
|
57
|
+
- Numbered steps (only when order matters):
|
|
58
|
+
<ol><li>Step one.</li><li>Step two.</li></ol>
|
|
59
|
+
- Bold for important terms or labels: <strong>important</strong>
|
|
60
|
+
- No <h1>/<h2> headings — use <strong> inline labels instead.
|
|
61
|
+
- No inline styles. No <div> wrappers. No Markdown (no **, no backticks, no #).
|
|
62
|
+
- Write in plain prose sentences; use lists only when there are three or more distinct items.
|
|
63
|
+
- Keep paragraphs short — summaries are displayed in compact UI containers (200-300px wide).
|
|
64
|
+
- Avoid long paragraphs; break complex ideas into <ul> lists for scanability.
|
|
65
|
+
|
|
66
|
+
## Call sequence markers
|
|
67
|
+
Some nodes list their dependencies in execution order, numbered from 1. A numbered line may
|
|
68
|
+
carry markers describing how that call is reached:
|
|
69
|
+
await — awaited here, so the next step runs only after it finishes
|
|
70
|
+
parallel — dispatched concurrently with its siblings, no order between them
|
|
71
|
+
loop — called repeatedly inside a loop
|
|
72
|
+
conditional — may be skipped (branch, guard, optional call)
|
|
73
|
+
deferred:X — runs after this function returns (X = timer, event, promise, ...)
|
|
74
|
+
reached xN — the same callee appears at N positions in the sequence
|
|
75
|
+
Use the positions and markers to describe control flow in order, but ground the summary in
|
|
76
|
+
the source code and the dependency summaries, not in the markers alone.
|
|
77
|
+
When a node has three or more ordered callees, the technical summary must name them in
|
|
78
|
+
execution order (for example "it first validates the payload, then persists the row, and
|
|
79
|
+
finally dispatches the email after the response returns"). Describe only the steps the
|
|
80
|
+
numbering actually lists - never invent a step that is not there. Nodes with fewer callees
|
|
81
|
+
need no such sentence.
|
|
82
|
+
|
|
83
|
+
## Security summary guidelines
|
|
84
|
+
The security_summary is displayed in a compact sidebar and a detail panel. Follow these rules:
|
|
85
|
+
- Lead with the specific vulnerability type (e.g. "SQL injection", "XSS", "exposed secret").
|
|
86
|
+
- Use <ul> lists when describing multiple risks or attack vectors.
|
|
87
|
+
- Mention the affected data or resource (e.g. "user credentials", "database contents").
|
|
88
|
+
- Keep it under 3 sentences for scanability.
|
|
89
|
+
- Example: <ul><li><strong>SQL injection</strong>: User input in <code>query</code> is passed directly to <code>db.execute()</code> without parameterization.</li><li>Attackers can extract or modify database contents.</li></ul>
|
|
90
|
+
|
|
91
|
+
## Severity guide
|
|
92
|
+
none — no security concerns
|
|
93
|
+
low — minor issue, limited impact (e.g. verbose error messages)
|
|
94
|
+
medium — potential vulnerability, needs attention (e.g. missing input validation)
|
|
78
95
|
high — serious vulnerability, could be exploited (e.g. SQL injection, exposed secrets, missing auth)`;
|
|
79
96
|
export function buildSystemPrompt(fingerprint) {
|
|
80
97
|
const lines = [];
|
|
@@ -104,12 +121,35 @@ export const EDGE_LABELS = {
|
|
|
104
121
|
TESTS: "Tests",
|
|
105
122
|
USES: "Uses"
|
|
106
123
|
};
|
|
124
|
+
// Renders the callOrder/v1 markers of one resolved callee. Booleans are only set
|
|
125
|
+
// when true, and `defer` says how the callee is detached from the current frame.
|
|
126
|
+
function callMarkers(rc) {
|
|
127
|
+
const marks = [];
|
|
128
|
+
if (rc.awaited)
|
|
129
|
+
marks.push("await");
|
|
130
|
+
if (rc.conc)
|
|
131
|
+
marks.push("parallel");
|
|
132
|
+
if (rc.repeat)
|
|
133
|
+
marks.push("loop");
|
|
134
|
+
if (rc.maybe)
|
|
135
|
+
marks.push("conditional");
|
|
136
|
+
if (rc.defer)
|
|
137
|
+
marks.push(`deferred:${rc.deferDetail ?? rc.defer}`);
|
|
138
|
+
if (rc.orders && rc.orders.length > 1)
|
|
139
|
+
marks.push(`reached x${rc.orders.length}`);
|
|
140
|
+
return marks.length > 0 ? ` (${marks.join(", ")})` : "";
|
|
141
|
+
}
|
|
107
142
|
// Renders a dep summary line — uses technicalSummary if available, else just the name.
|
|
108
|
-
|
|
143
|
+
// `position` numbers the callee in execution order; `label` distinguishes non-CALLS
|
|
144
|
+
// edge types inside an otherwise ordered block.
|
|
145
|
+
function depLine(depNode, opts) {
|
|
109
146
|
const summary = depNode.technicalSummary
|
|
110
147
|
? ` — ${depNode.technicalSummary.slice(0, 120)}`
|
|
111
148
|
: "";
|
|
112
|
-
|
|
149
|
+
const position = opts?.position !== undefined ? `${opts.position}. ` : "";
|
|
150
|
+
const kind = opts?.label && opts.label !== "Calls" ? ` [${opts.label}]` : "";
|
|
151
|
+
const markers = opts?.rc ? callMarkers(opts.rc) : "";
|
|
152
|
+
return ` ${position}${depNode.name} [${depNode.type}]${kind}${markers}${summary}`;
|
|
113
153
|
}
|
|
114
154
|
// ─── User Prompt Builder ──────────────────────────────────────────────────────
|
|
115
155
|
function buildUserPrompt(ctx) {
|
|
@@ -124,17 +164,38 @@ function buildUserPrompt(ctx) {
|
|
|
124
164
|
parts.push(node.rawCode ?? "(source not available)");
|
|
125
165
|
parts.push("```");
|
|
126
166
|
// ── Dependencies (outgoing edges) — O(1) lookup ───────────────
|
|
167
|
+
//
|
|
168
|
+
// Execution order comes from the node's own metadata.resolvedCalls; edges are
|
|
169
|
+
// structure only (docs/CALL_ORDER.md §3.2). Callees that carry a position are
|
|
170
|
+
// rendered as one numbered sequence, everything else keeps the labelled form.
|
|
127
171
|
const outgoing = edgeIndex.outgoing.get(node.id);
|
|
128
172
|
if (outgoing && outgoing.size > 0) {
|
|
173
|
+
const ordered = new Map();
|
|
174
|
+
for (const rc of node.metadata?.resolvedCalls ?? []) {
|
|
175
|
+
if (typeof rc.firstOrder === "number")
|
|
176
|
+
ordered.set(rc.nodeId, rc);
|
|
177
|
+
}
|
|
178
|
+
const sequence = [];
|
|
129
179
|
const depLines = [];
|
|
130
180
|
for (const [edgeType, targetIds] of outgoing) {
|
|
131
181
|
const label = EDGE_LABELS[edgeType] ?? edgeType;
|
|
132
182
|
for (const targetId of targetIds) {
|
|
133
183
|
const depNode = allNodes.get(targetId);
|
|
134
|
-
if (depNode)
|
|
184
|
+
if (!depNode)
|
|
185
|
+
continue;
|
|
186
|
+
const rc = ordered.get(targetId);
|
|
187
|
+
if (rc)
|
|
188
|
+
sequence.push({ dep: depNode, rc, label });
|
|
189
|
+
else
|
|
135
190
|
depLines.push(`${label}:\n${depLine(depNode)}`);
|
|
136
191
|
}
|
|
137
192
|
}
|
|
193
|
+
if (sequence.length > 0) {
|
|
194
|
+
sequence.sort((a, b) => (a.rc.firstOrder ?? 0) - (b.rc.firstOrder ?? 0) || a.dep.name.localeCompare(b.dep.name));
|
|
195
|
+
parts.push("");
|
|
196
|
+
parts.push("### Call sequence (execution order)");
|
|
197
|
+
sequence.forEach((step, i) => parts.push(depLine(step.dep, { rc: step.rc, position: i + 1, label: step.label })));
|
|
198
|
+
}
|
|
138
199
|
if (depLines.length > 0) {
|
|
139
200
|
parts.push("");
|
|
140
201
|
parts.push("### Dependencies");
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
import { describe, expect, test } from "bun:test";
|
|
2
|
+
import { buildPrompt, buildSystemPrompt } from "./prompts.js";
|
|
3
|
+
function node(over) {
|
|
4
|
+
return {
|
|
5
|
+
type: "FUNCTION",
|
|
6
|
+
filePath: "src/handler.ts",
|
|
7
|
+
startLine: 1,
|
|
8
|
+
endLine: 10,
|
|
9
|
+
metadata: {},
|
|
10
|
+
...over,
|
|
11
|
+
};
|
|
12
|
+
}
|
|
13
|
+
function ctx(node, allNodes, systemPrompt = "SYS") {
|
|
14
|
+
const outgoing = new Map();
|
|
15
|
+
for (const dep of allNodes) {
|
|
16
|
+
if (!outgoing.has(node.id))
|
|
17
|
+
outgoing.set(node.id, new Map());
|
|
18
|
+
const inner = outgoing.get(node.id);
|
|
19
|
+
if (!inner.has("CALLS"))
|
|
20
|
+
inner.set("CALLS", []);
|
|
21
|
+
inner.get("CALLS").push(dep.id);
|
|
22
|
+
}
|
|
23
|
+
return {
|
|
24
|
+
node,
|
|
25
|
+
allNodes: new Map(allNodes.map((n) => [n.id, n])),
|
|
26
|
+
edgeIndex: { outgoing, incoming: new Map() },
|
|
27
|
+
routeIndex: { byFilePath: new Map() },
|
|
28
|
+
systemPrompt,
|
|
29
|
+
};
|
|
30
|
+
}
|
|
31
|
+
const userPrompt = (c) => buildPrompt(c)[1].content;
|
|
32
|
+
describe("summarizer prompt — call order", () => {
|
|
33
|
+
const parseBody = node({
|
|
34
|
+
id: "f::parseBody", name: "parseBody", technicalSummary: "Reads the raw request body.",
|
|
35
|
+
});
|
|
36
|
+
const validate = node({
|
|
37
|
+
id: "f::validateUser", name: "validateUser", technicalSummary: "Checks the payload against schema rules.",
|
|
38
|
+
});
|
|
39
|
+
const save = node({
|
|
40
|
+
id: "f::save", name: "save", technicalSummary: "Upserts the user row.",
|
|
41
|
+
});
|
|
42
|
+
const notify = node({
|
|
43
|
+
id: "f::notify", name: "sendEmail", technicalSummary: "Queues the welcome email.",
|
|
44
|
+
});
|
|
45
|
+
// Deliberately passed in a different order than the call order, so the test
|
|
46
|
+
// fails if we render edge/insertion order instead of firstOrder.
|
|
47
|
+
const resolved = [
|
|
48
|
+
{ name: "save", nodeId: "f::save", firstOrder: 3, repeat: true, maybe: true },
|
|
49
|
+
{ name: "parseBody", nodeId: "f::parseBody", firstOrder: 1, awaited: true },
|
|
50
|
+
{ name: "validateUser", nodeId: "f::validateUser", firstOrder: 2 },
|
|
51
|
+
{ name: "sendEmail", nodeId: "f::notify", firstOrder: 4, defer: "timer" },
|
|
52
|
+
];
|
|
53
|
+
const caller = node({
|
|
54
|
+
id: "f::handler",
|
|
55
|
+
name: "handler",
|
|
56
|
+
rawCode: "async function handler(req) { ... }",
|
|
57
|
+
metadata: { resolvedCalls: resolved },
|
|
58
|
+
});
|
|
59
|
+
test("callees are numbered in execution order, not edge order", () => {
|
|
60
|
+
const prompt = userPrompt(ctx(caller, [save, parseBody, validate, notify]));
|
|
61
|
+
const lines = prompt.split("\n").filter((l) => /^\s+\d+\. /.test(l));
|
|
62
|
+
expect(lines).toHaveLength(4);
|
|
63
|
+
expect(lines[0]).toContain("1. parseBody");
|
|
64
|
+
expect(lines[1]).toContain("2. validateUser");
|
|
65
|
+
expect(lines[2]).toContain("3. save");
|
|
66
|
+
expect(lines[3]).toContain("4. sendEmail");
|
|
67
|
+
});
|
|
68
|
+
test("markers are rendered from the resolved call record", () => {
|
|
69
|
+
const prompt = userPrompt(ctx(caller, [parseBody, validate, save, notify]));
|
|
70
|
+
expect(prompt).toContain("1. parseBody [FUNCTION] (await)");
|
|
71
|
+
expect(prompt).toContain("3. save [FUNCTION] (loop, conditional)");
|
|
72
|
+
expect(prompt).toContain("4. sendEmail [FUNCTION] (deferred:timer)");
|
|
73
|
+
// no markers on an unconditional, awaited-free callee
|
|
74
|
+
expect(prompt).toContain("2. validateUser [FUNCTION] —");
|
|
75
|
+
});
|
|
76
|
+
test("callee summaries are still included", () => {
|
|
77
|
+
const prompt = userPrompt(ctx(caller, [parseBody, validate, save, notify]));
|
|
78
|
+
expect(prompt).toContain("Reads the raw request body.");
|
|
79
|
+
expect(prompt).toContain("Checks the payload against schema rules.");
|
|
80
|
+
expect(prompt).toContain("Upserts the user row.");
|
|
81
|
+
});
|
|
82
|
+
test("repeated callees report how many positions reached them", () => {
|
|
83
|
+
const twice = node({
|
|
84
|
+
id: "f::dup", name: "dup",
|
|
85
|
+
metadata: {
|
|
86
|
+
resolvedCalls: [
|
|
87
|
+
{ name: "a", nodeId: "f::a", firstOrder: 1, orders: [1, 3] },
|
|
88
|
+
],
|
|
89
|
+
},
|
|
90
|
+
});
|
|
91
|
+
const a = node({ id: "f::a", name: "a", technicalSummary: "Does a." });
|
|
92
|
+
expect(userPrompt(ctx(twice, [a]))).toContain("(reached x2)");
|
|
93
|
+
});
|
|
94
|
+
test("a node without ordering renders exactly as before", () => {
|
|
95
|
+
const plain = node({ id: "f::plain", name: "plain", metadata: {} });
|
|
96
|
+
const prompt = userPrompt(ctx(plain, [parseBody, validate]));
|
|
97
|
+
expect(prompt).not.toContain("Call sequence");
|
|
98
|
+
expect(prompt).toContain("### Dependencies");
|
|
99
|
+
expect(prompt).toContain("Calls:\n parseBody [FUNCTION]");
|
|
100
|
+
});
|
|
101
|
+
test("system prompt documents every marker", () => {
|
|
102
|
+
const sys = buildSystemPrompt({
|
|
103
|
+
framework: "next", language: "typescript", projectType: "web",
|
|
104
|
+
stateManagement: [], databases: [], dataFetching: [],
|
|
105
|
+
});
|
|
106
|
+
for (const marker of ["await", "parallel", "loop", "conditional", "deferred", "reached xN"]) {
|
|
107
|
+
expect(sys).toContain(marker);
|
|
108
|
+
}
|
|
109
|
+
// The ordered flow is only useful if the summary narrates it.
|
|
110
|
+
expect(sys).toContain("three or more ordered callees");
|
|
111
|
+
});
|
|
112
|
+
});
|
package/dist/types.d.ts
CHANGED
|
@@ -53,6 +53,69 @@ export interface CallSite {
|
|
|
53
53
|
argCount: number;
|
|
54
54
|
argTypes?: string[];
|
|
55
55
|
hasSpread?: boolean;
|
|
56
|
+
/** "call" (default) or "hook" (use*). Hooks are excluded from metadata.calls. */
|
|
57
|
+
kind?: CallSiteKind;
|
|
58
|
+
/** 1-based lexical rank among every recorded site of the owner node. */
|
|
59
|
+
order?: number;
|
|
60
|
+
/** 1-based line of the call expression in the file. */
|
|
61
|
+
line?: number;
|
|
62
|
+
/** 0-based column, so two calls on one line stay distinguishable. */
|
|
63
|
+
col?: number;
|
|
64
|
+
/** `order` of the enclosing call expression: foo(bar()) → bar.nested = foo.order. */
|
|
65
|
+
nested?: number;
|
|
66
|
+
/** Which execution region the site belongs to. Default "inline". */
|
|
67
|
+
scope?: CallScope;
|
|
68
|
+
/** The frame suspends on this call (await). */
|
|
69
|
+
awaited?: boolean;
|
|
70
|
+
/** When it runs relative to the frame. Absent = no evidence of detachment. */
|
|
71
|
+
defer?: DeferKind;
|
|
72
|
+
/** Provenance for the scheduler symbol ("tokio::spawn", "useEffect"). */
|
|
73
|
+
deferDetail?: string;
|
|
74
|
+
/** May run in parallel with the frame (thread / task / goroutine). */
|
|
75
|
+
conc?: boolean;
|
|
76
|
+
/** May execute 0..N times (loop body or iteration callback). */
|
|
77
|
+
repeat?: boolean;
|
|
78
|
+
/** May execute 0 times (branch / short-circuit / catch). */
|
|
79
|
+
maybe?: boolean;
|
|
80
|
+
/** Its result can abort the remaining calls in the block (Rust `?`). */
|
|
81
|
+
earlyExit?: boolean;
|
|
82
|
+
}
|
|
83
|
+
export type CallSiteKind = "call" | "hook";
|
|
84
|
+
/**
|
|
85
|
+
* Execution region of a call site.
|
|
86
|
+
* inline — runs in the owner's frame body (normal straight-line path)
|
|
87
|
+
* callback — inside a callback/closure passed to a call (timer, promise, hook, map…)
|
|
88
|
+
* handler — inside a JSX attribute expression / externally triggered registration
|
|
89
|
+
* nested — inside a function declared inside the owner (it has no node of its own)
|
|
90
|
+
* module — FILE node: runs at module load
|
|
91
|
+
*/
|
|
92
|
+
export type CallScope = "inline" | "callback" | "handler" | "nested" | "module";
|
|
93
|
+
/**
|
|
94
|
+
* When a detached call runs relative to the frame. Absent = no evidence of
|
|
95
|
+
* detachment (never a guarantee of inline execution).
|
|
96
|
+
*/
|
|
97
|
+
export type DeferKind = "timer" | "promise" | "microtask" | "event" | "postRender" | "onReturn" | "unknown";
|
|
98
|
+
/**
|
|
99
|
+
* One entry of `metadata.resolvedCalls`: the first call site that resolved to a
|
|
100
|
+
* local/third-party node. `callSites` keeps the complete per-occurrence truth;
|
|
101
|
+
* this is the compact view a renderer needs for one edge, deliberately small so
|
|
102
|
+
* the cloud can ship it as a jsonb slice.
|
|
103
|
+
*/
|
|
104
|
+
export interface ResolvedCall {
|
|
105
|
+
name: string;
|
|
106
|
+
nodeId: string;
|
|
107
|
+
firstOrder?: number;
|
|
108
|
+
line?: number;
|
|
109
|
+
defer?: DeferKind;
|
|
110
|
+
deferDetail?: string;
|
|
111
|
+
awaited?: boolean;
|
|
112
|
+
conc?: boolean;
|
|
113
|
+
repeat?: boolean;
|
|
114
|
+
maybe?: boolean;
|
|
115
|
+
/** Every ordinal that reached this target, ascending, only when > 1. The
|
|
116
|
+
* node carries the repeat positions itself so no consumer needs the edge
|
|
117
|
+
* mirror (docs/CALL_ORDER.md §3.2). */
|
|
118
|
+
orders?: number[];
|
|
56
119
|
}
|
|
57
120
|
export interface CodeNode {
|
|
58
121
|
id: string;
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare const engineVersion: string;
|
package/dist/version.js
ADDED
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|