devlensio 1.2.0 → 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.
Files changed (47) hide show
  1. package/dist/graph/edges/callEdges.js +77 -3
  2. package/dist/graph/edges/callEdges.test.js +1 -1
  3. package/dist/graph/edges/callOrder.test.d.ts +1 -0
  4. package/dist/graph/edges/callOrder.test.js +227 -0
  5. package/dist/graph/edges/propEdges.js +6 -1
  6. package/dist/index.d.ts +1 -0
  7. package/dist/index.js +1 -0
  8. package/dist/parser/callFlow.d.ts +15 -0
  9. package/dist/parser/callFlow.js +302 -0
  10. package/dist/parser/callOrder.test.d.ts +1 -0
  11. package/dist/parser/callOrder.test.js +407 -0
  12. package/dist/parser/extractors/components.js +18 -28
  13. package/dist/parser/extractors/functions.d.ts +12 -3
  14. package/dist/parser/extractors/functions.js +58 -36
  15. package/dist/parser/extractors/moduleScope.js +1 -1
  16. package/dist/parser/moduleScope.test.js +5 -3
  17. package/dist/summarizer/index.js +53 -4
  18. package/dist/summarizer/prompts.js +111 -50
  19. package/dist/summarizer/prompts.test.d.ts +1 -0
  20. package/dist/summarizer/prompts.test.js +112 -0
  21. package/dist/types.d.ts +63 -0
  22. package/dist/version.d.ts +1 -0
  23. package/dist/version.js +2 -0
  24. package/extractors/go/bin/darwin-amd64/devlens_go_extractor +0 -0
  25. package/extractors/go/bin/darwin-arm64/devlens_go_extractor +0 -0
  26. package/extractors/go/bin/linux-amd64/devlens_go_extractor +0 -0
  27. package/extractors/go/bin/linux-arm64/devlens_go_extractor +0 -0
  28. package/extractors/go/bin/windows-amd64/devlens_go_extractor.exe +0 -0
  29. package/extractors/go/calls.go +89 -10
  30. package/extractors/go/nodes.go +29 -11
  31. package/extractors/go/parser.go +311 -21
  32. package/extractors/java/devlens_java_extractor.jar +0 -0
  33. package/extractors/java/src/devlens/extractor/Extractor.java +36 -10
  34. package/extractors/java/src/devlens/extractor/Parser.java +387 -0
  35. package/extractors/java/src/devlens/extractor/edges/Calls.java +66 -10
  36. package/extractors/python/devlens_extractors_python/edges/calls.py +26 -3
  37. package/extractors/python/devlens_extractors_python/parser/__init__.py +4 -3
  38. package/extractors/python/devlens_extractors_python/parser/functions.py +199 -42
  39. package/extractors/rust/bin/darwin-amd64/devlens_rust_extractor +0 -0
  40. package/extractors/rust/bin/darwin-arm64/devlens_rust_extractor +0 -0
  41. package/extractors/rust/bin/linux-amd64/devlens_rust_extractor +0 -0
  42. package/extractors/rust/bin/linux-arm64/devlens_rust_extractor +0 -0
  43. package/extractors/rust/bin/windows-amd64/devlens_rust_extractor.exe +0 -0
  44. package/extractors/rust/src/calls.rs +82 -8
  45. package/extractors/rust/src/nodes.rs +29 -0
  46. package/extractors/rust/src/parser.rs +362 -27
  47. package/package.json +77 -73
@@ -44,7 +44,7 @@ const SKIP_TOP_LEVEL = new Set([
44
44
  * Returns EMPTY data for files with no module-scope calls.
45
45
  */
46
46
  export function extractModuleScopeCalls(file) {
47
- const acc = createCallAccumulator();
47
+ const acc = createCallAccumulator({ owner: file, isFileOwner: true });
48
48
  for (const stmt of file.getStatements()) {
49
49
  if (SKIP_TOP_LEVEL.has(stmt.getKind()))
50
50
  continue;
@@ -30,7 +30,9 @@ describe("extractModuleScopeCalls — scope rule", () => {
30
30
  const cleanup = startAll();
31
31
  `);
32
32
  expect(data.calls).toEqual(["startAll"]);
33
- expect(data.callSites).toEqual([{ name: "startAll", argCount: 0, argTypes: [] }]);
33
+ expect(data.callSites).toEqual([
34
+ expect.objectContaining({ name: "startAll", argCount: 0, order: 1, scope: "module", line: 3 }),
35
+ ]);
34
36
  });
35
37
  it("collects calls inside a top-level if block", () => {
36
38
  const data = parse(`
@@ -143,8 +145,8 @@ describe("parseRepo — module-scope metadata on FILE nodes", () => {
143
145
  expect(file.type).toBe("FILE");
144
146
  expect(file.metadata.calls).toEqual(["startAll", "process.on"]);
145
147
  expect(file.metadata.callSites).toEqual([
146
- { name: "startAll", argCount: 0, argTypes: [] },
147
- { name: "process.on", argCount: 2, argTypes: ["string", "unknown"] },
148
+ expect.objectContaining({ name: "startAll", argCount: 0, order: 1, scope: "module" }),
149
+ expect.objectContaining({ name: "process.on", argCount: 2, argTypes: ["string", "unknown"], order: 2, scope: "module" }),
148
150
  ]);
149
151
  deleteFakeRepo(repo);
150
152
  });
@@ -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
- // All nodes in this level summarized in parallel
196
- await Promise.all(nodes.map(summarizeNode));
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 Promise.all(nodes.map(summarizeNode));
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 Promise.all(batchNodes.map(summarizeNode));
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
- ## Security summary guidelines
67
- The security_summary is displayed in a compact sidebar and a detail panel. Follow these rules:
68
- - Lead with the specific vulnerability type (e.g. "SQL injection", "XSS", "exposed secret").
69
- - Use <ul> lists when describing multiple risks or attack vectors.
70
- - Mention the affected data or resource (e.g. "user credentials", "database contents").
71
- - Keep it under 3 sentences for scanability.
72
- - 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>
73
-
74
- ## Severity guide
75
- none — no security concerns
76
- low — minor issue, limited impact (e.g. verbose error messages)
77
- medium — potential vulnerability, needs attention (e.g. missing input validation)
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
- function depLine(depNode) {
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
- return ` ${depNode.name} [${depNode.type}]${summary}`;
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;
@@ -0,0 +1,2 @@
1
+ import packageJSON from "../package.json" with { type: "json" };
2
+ export const engineVersion = packageJSON.version;