ts-knowledge-graph 0.1.2 → 0.1.6

package/dist/enrich/runtime_enricher.js

@@ -0,0 +1,98 @@
+import { RUNTIME_MANIFEST_KEY } from '../schema/runtime_manifest.js';
+import { CpuProfile } from './cpu_profile.js';
+import { RuntimeJoin } from './runtime_join.js';
+/** The telemetry source tag written into `metadata.runtime.source`. */
+export const RUNTIME_SOURCE_CPU_PROFILE = 'v8-cpuprofile';
+/** Namespaced key under which runtime metrics are stored on a node's metadata. */
+export const RUNTIME_METADATA_KEY = 'runtime';
+/** Edge kind under which the runtime call graph extracted from the profile is stored. */
+export const RUNTIME_CALL_EDGE_KIND = 'CALLS_RUNTIME';
+export class RuntimeEnricher {
+    /**
+     * Ingests a V8 CPU profile and attaches `metadata.runtime` (self time and
+     * sample count) onto the graph nodes whose ranges enclose the profiled
+     * frames. Existing metadata is preserved; only the `runtime` key is written,
+     * so re-running with the same profile is idempotent. Unmatched frames are
+     * counted and returned in the report rather than dropped silently.
+     */
+    static async enrich(store, profileText, options) {
+        const profile = CpuProfile.parse(profileText);
+        const frames = CpuProfile.aggregate(profile);
+        const nodes = await store.readNodes();
+        const result = RuntimeJoin.join(nodes, frames, { root: options.root });
+        const nodeById = new Map(nodes.map((node) => [node.id, node]));
+        const updates = [];
+        const hotspots = [];
+        for (const [id, attribution] of result.attributions) {
+            const node = nodeById.get(id);
+            if (node === undefined) {
+                continue;
+            }
+            const metrics = RuntimeEnricher.toMetrics(attribution);
+            updates.push({
+                id,
+                metadata: { ...node.metadata, [RUNTIME_METADATA_KEY]: metrics },
+            });
+            hotspots.push({
+                id,
+                name: node.name,
+                kind: node.kind,
+                filePath: node.filePath,
+                selfMs: metrics.selfMs,
+                samples: metrics.samples,
+            });
+        }
+        await store.writeNodeMetadata(updates);
+        const manifest = {
+            source: RUNTIME_SOURCE_CPU_PROFILE,
+            totalSamples: CpuProfile.totalSamples(profile),
+            matchedSamples: result.matchedSamples,
+            totalSelfMicros: result.matchedSelfMicros + result.droppedSelfMicros,
+            matchedSelfMicros: result.matchedSelfMicros,
+        };
+        await store.writeGraphMeta(RUNTIME_MANIFEST_KEY, manifest);
+        const callEdges = CpuProfile.callEdges(profile);
+        const edgeResult = RuntimeJoin.joinCallEdges(nodes, callEdges, { root: options.root });
+        await store.clearEdgesByKind(RUNTIME_CALL_EDGE_KIND);
+        await store.writeEdges(edgeResult.edges.map((edge) => RuntimeEnricher.toCallEdge(edge)));
+        hotspots.sort((a, b) => b.selfMs - a.selfMs || b.samples - a.samples);
+        return {
+            totalSamples: CpuProfile.totalSamples(profile),
+            matchedNodes: updates.length,
+            matchedFrames: result.matchedFrames,
+            matchedSamples: result.matchedSamples,
+            matchedSelfMs: RuntimeEnricher.microsToMs(result.matchedSelfMicros),
+            matchedByName: result.matchedByName,
+            matchedByRange: result.matchedByRange,
+            droppedFrames: result.droppedFrames,
+            droppedSamples: result.droppedSamples,
+            runtimeEdges: edgeResult.matchedEdges,
+            droppedCallEdges: edgeResult.droppedEdges,
+            dropped: result.dropped,
+            hotspots,
+        };
+    }
+    static toMetrics(attribution) {
+        return {
+            source: RUNTIME_SOURCE_CPU_PROFILE,
+            samples: attribution.samples,
+            selfMicros: attribution.selfMicros,
+            selfMs: RuntimeEnricher.microsToMs(attribution.selfMicros),
+        };
+    }
+    /** Builds a `CALLS_RUNTIME` graph edge from a resolved runtime call edge, weighted by its sample count. */
+    static toCallEdge(edge) {
+        return {
+            id: `${RUNTIME_CALL_EDGE_KIND}:${edge.from}->${edge.to}`,
+            kind: RUNTIME_CALL_EDGE_KIND,
+            from: edge.from,
+            to: edge.to,
+            metadata: { source: RUNTIME_SOURCE_CPU_PROFILE, samples: edge.samples },
+        };
+    }
+    /** Converts microseconds to milliseconds, rounded to microsecond precision. */
+    static microsToMs(micros) {
+        return Math.round(micros) / 1000;
+    }
+}
+//# sourceMappingURL=runtime_enricher.js.map

package/dist/enrich/runtime_enricher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime_enricher.js","sourceRoot":"","sources":["../../src/enrich/runtime_enricher.ts"],"names":[],"mappings":"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"}

package/dist/enrich/runtime_join.d.ts

@@ -0,0 +1,124 @@
+import { FrameSample, RuntimeCallEdge } from './cpu_profile.js';
+/** A graph node reduced to the fields the join needs. */
+export type RuntimeTargetNode = {
+    id: string;
+    kind: string;
+    name: string;
+    filePath: string;
+    startLine: number;
+    endLine: number;
+};
+/** Self time and sample count attributed to one graph node. */
+export type RuntimeAttribution = {
+    samples: number;
+    selfMicros: number;
+};
+/** How a frame was attached to its node — by symbol name or by line range. */
+export type MatchVia = 'name' | 'range';
+/**
+ * A group of profile frames that could not be attached to a single graph node,
+ * aggregated by a human-readable label so coverage gaps are reportable rather
+ * than silently lost. `ambiguous` means the frame's name matched several nodes
+ * in the file and the (transpiled) line could not break the tie.
+ */
+export type DroppedFrameGroup = {
+    label: string;
+    reason: 'no-file' | 'no-node' | 'ambiguous';
+    samples: number;
+    selfMicros: number;
+};
+export type RuntimeJoinResult = {
+    attributions: Map<string, RuntimeAttribution>;
+    matchedFrames: number;
+    matchedSamples: number;
+    matchedSelfMicros: number;
+    matchedByName: number;
+    matchedByRange: number;
+    droppedFrames: number;
+    droppedSamples: number;
+    droppedSelfMicros: number;
+    dropped: DroppedFrameGroup[];
+};
+export type RuntimeJoinOptions = {
+    /** Project root the profile's absolute frame urls are resolved against. */
+    root: string;
+};
+/** A runtime call edge resolved onto graph node ids, weighted by the samples that flowed through it. */
+export type RuntimeEdge = {
+    from: string;
+    to: string;
+    samples: number;
+};
+/** The outcome of joining the profile's call-tree edges onto graph nodes. */
+export type RuntimeCallJoinResult = {
+    edges: RuntimeEdge[];
+    matchedEdges: number;
+    droppedEdges: number;
+    droppedSamples: number;
+};
+export declare class RuntimeJoin {
+    /**
+     * Joins profile frames onto graph nodes with a hybrid key that survives
+     * transpilation.
+     *
+     * For each frame the url is resolved to a graph `filePath`, then within that
+     * file:
+     * 1. **By name** — a frame's `functionName` matched against node names. A
+     *    unique match wins outright; this is the path that works when a
+     *    transpiler (tsx/esbuild) has collapsed line numbers, since the function
+     *    name is still intact.
+     * 2. **By range** — when the name is absent or matches nothing, the innermost
+     *    node whose `[startLine, endLine]` encloses the frame line. This is the
+     *    precise path for line-preserving runs and also disambiguates a name that
+     *    matched several nodes.
+     *
+     * Frames resolving to no in-project file, to a file with no matching node, or
+     * to an unbreakable name tie are counted and reported as dropped — never
+     * attached.
+     */
+    static join(nodes: RuntimeTargetNode[], frames: FrameSample[], options: RuntimeJoinOptions): RuntimeJoinResult;
+    /**
+     * Joins the profile's call-tree edges onto graph node ids, reusing the same
+     * per-frame resolution as {@link join} (name match, then enclosing range) for
+     * both endpoints. Edges whose caller or callee resolves to nothing, and
+     * self-edges (recursion landing on one node), are dropped and counted; the
+     * survivors are aggregated by node pair, summing the samples that flowed through
+     * each call.
+     */
+    static joinCallEdges(nodes: RuntimeTargetNode[], callEdges: RuntimeCallEdge[], options: RuntimeJoinOptions): RuntimeCallJoinResult;
+    /** Resolves a single frame to its graph node — file path, then name-or-range within that file — or undefined. */
+    private static resolveFrame;
+    private static indexByFile;
+    /**
+     * Resolves a frame to a node within its file, preferring a name match and
+     * falling back to an enclosing-range match.
+     */
+    private static resolveNode;
+    /**
+     * Nodes in the file whose name equals the frame's function name (or its final
+     * dotted segment, so `Widget.render` matches a method named `render`). V8
+     * synthetic frames such as `(anonymous)` and `(root)` never match.
+     */
+    private static nameMatches;
+    private static isMeaningfulName;
+    private static candidateNames;
+    /**
+     * Picks the innermost node whose range encloses `line`. Ties on range width
+     * break toward the later-starting node, which is the more deeply nested
+     * declaration. A non-positive line (V8 synthetic frame, or a transpiler that
+     * collapsed line numbers) encloses nothing.
+     */
+    private static enclosingNode;
+    /**
+     * Maps a profile frame url to a graph `filePath`. Node-internal and empty
+     * urls (`node:`, `(root)`, `(idle)`) resolve to nothing. A url inside `root`
+     * resolves by relative path; otherwise a unique path-suffix match is used so
+     * a graph extracted under a different absolute prefix still attaches.
+     */
+    private static resolveFilePath;
+    private static urlToAbsolute;
+    private static toPosix;
+    private static recordDrop;
+    private static dropLabel;
+}
+//# sourceMappingURL=runtime_join.d.ts.map

package/dist/enrich/runtime_join.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime_join.d.ts","sourceRoot":"","sources":["../../src/enrich/runtime_join.ts"],"names":[],"mappings":"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"}

package/dist/enrich/runtime_join.js

@@ -0,0 +1,270 @@
+import { isAbsolute, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Node kinds a CPU frame can plausibly name. Restricting name matching to these
+ * avoids attaching an executing frame to a same-named type or enum member.
+ */
+const NAME_MATCH_KINDS = new Set(['Function', 'Method', 'Property', 'Variable', 'Class']);
+export class RuntimeJoin {
+    /**
+     * Joins profile frames onto graph nodes with a hybrid key that survives
+     * transpilation.
+     *
+     * For each frame the url is resolved to a graph `filePath`, then within that
+     * file:
+     * 1. **By name** — a frame's `functionName` matched against node names. A
+     *    unique match wins outright; this is the path that works when a
+     *    transpiler (tsx/esbuild) has collapsed line numbers, since the function
+     *    name is still intact.
+     * 2. **By range** — when the name is absent or matches nothing, the innermost
+     *    node whose `[startLine, endLine]` encloses the frame line. This is the
+     *    precise path for line-preserving runs and also disambiguates a name that
+     *    matched several nodes.
+     *
+     * Frames resolving to no in-project file, to a file with no matching node, or
+     * to an unbreakable name tie are counted and reported as dropped — never
+     * attached.
+     */
+    static join(nodes, frames, options) {
+        const byFile = RuntimeJoin.indexByFile(nodes);
+        const filePaths = [...byFile.keys()];
+        const attributions = new Map();
+        const dropped = new Map();
+        let matchedFrames = 0;
+        let matchedSamples = 0;
+        let matchedSelfMicros = 0;
+        let matchedByName = 0;
+        let matchedByRange = 0;
+        let droppedFrames = 0;
+        let droppedSamples = 0;
+        let droppedSelfMicros = 0;
+        for (const frame of frames) {
+            const filePath = RuntimeJoin.resolveFilePath(frame.url, options.root, byFile, filePaths);
+            if (filePath === undefined) {
+                RuntimeJoin.recordDrop(dropped, frame, 'no-file');
+                droppedFrames += 1;
+                droppedSamples += frame.samples;
+                droppedSelfMicros += frame.selfMicros;
+                continue;
+            }
+            const resolution = RuntimeJoin.resolveNode(byFile.get(filePath) ?? [], frame);
+            if (resolution.node === undefined) {
+                RuntimeJoin.recordDrop(dropped, frame, resolution.reason);
+                droppedFrames += 1;
+                droppedSamples += frame.samples;
+                droppedSelfMicros += frame.selfMicros;
+                continue;
+            }
+            const current = attributions.get(resolution.node.id) ?? { samples: 0, selfMicros: 0 };
+            current.samples += frame.samples;
+            current.selfMicros += frame.selfMicros;
+            attributions.set(resolution.node.id, current);
+            matchedFrames += 1;
+            matchedSamples += frame.samples;
+            matchedSelfMicros += frame.selfMicros;
+            if (resolution.via === 'name') {
+                matchedByName += 1;
+            }
+            else {
+                matchedByRange += 1;
+            }
+        }
+        return {
+            attributions,
+            matchedFrames,
+            matchedSamples,
+            matchedSelfMicros,
+            matchedByName,
+            matchedByRange,
+            droppedFrames,
+            droppedSamples,
+            droppedSelfMicros,
+            dropped: [...dropped.values()].sort((a, b) => b.selfMicros - a.selfMicros),
+        };
+    }
+    /**
+     * Joins the profile's call-tree edges onto graph node ids, reusing the same
+     * per-frame resolution as {@link join} (name match, then enclosing range) for
+     * both endpoints. Edges whose caller or callee resolves to nothing, and
+     * self-edges (recursion landing on one node), are dropped and counted; the
+     * survivors are aggregated by node pair, summing the samples that flowed through
+     * each call.
+     */
+    static joinCallEdges(nodes, callEdges, options) {
+        const byFile = RuntimeJoin.indexByFile(nodes);
+        const filePaths = [...byFile.keys()];
+        const aggregated = new Map();
+        let matchedEdges = 0;
+        let droppedEdges = 0;
+        let droppedSamples = 0;
+        for (const edge of callEdges) {
+            const from = RuntimeJoin.resolveFrame(edge.caller, byFile, filePaths, options.root);
+            const to = RuntimeJoin.resolveFrame(edge.callee, byFile, filePaths, options.root);
+            if (from === undefined || to === undefined || from.id === to.id) {
+                droppedEdges += 1;
+                droppedSamples += edge.samples;
+                continue;
+            }
+            const key = `${from.id}->${to.id}`;
+            const existing = aggregated.get(key);
+            if (existing === undefined) {
+                aggregated.set(key, { from: from.id, to: to.id, samples: edge.samples });
+            }
+            else {
+                existing.samples += edge.samples;
+            }
+            matchedEdges += 1;
+        }
+        return { edges: [...aggregated.values()], matchedEdges, droppedEdges, droppedSamples };
+    }
+    /** Resolves a single frame to its graph node — file path, then name-or-range within that file — or undefined. */
+    static resolveFrame(frame, byFile, filePaths, root) {
+        const filePath = RuntimeJoin.resolveFilePath(frame.url, root, byFile, filePaths);
+        if (filePath === undefined) {
+            return undefined;
+        }
+        return RuntimeJoin.resolveNode(byFile.get(filePath) ?? [], frame).node;
+    }
+    static indexByFile(nodes) {
+        const byFile = new Map();
+        for (const node of nodes) {
+            const bucket = byFile.get(node.filePath);
+            if (bucket === undefined) {
+                byFile.set(node.filePath, [node]);
+            }
+            else {
+                bucket.push(node);
+            }
+        }
+        return byFile;
+    }
+    /**
+     * Resolves a frame to a node within its file, preferring a name match and
+     * falling back to an enclosing-range match.
+     */
+    static resolveNode(fileNodes, frame) {
+        const nameMatches = RuntimeJoin.nameMatches(fileNodes, frame.functionName);
+        if (nameMatches.length === 1) {
+            return { node: nameMatches[0], via: 'name' };
+        }
+        if (nameMatches.length > 1) {
+            const disambiguated = RuntimeJoin.enclosingNode(nameMatches, frame.line);
+            if (disambiguated !== undefined) {
+                return { node: disambiguated, via: 'name' };
+            }
+            return { node: undefined, reason: 'ambiguous' };
+        }
+        const enclosed = RuntimeJoin.enclosingNode(fileNodes, frame.line);
+        if (enclosed !== undefined) {
+            return { node: enclosed, via: 'range' };
+        }
+        return { node: undefined, reason: 'no-node' };
+    }
+    /**
+     * Nodes in the file whose name equals the frame's function name (or its final
+     * dotted segment, so `Widget.render` matches a method named `render`). V8
+     * synthetic frames such as `(anonymous)` and `(root)` never match.
+     */
+    static nameMatches(fileNodes, functionName) {
+        if (RuntimeJoin.isMeaningfulName(functionName) === false) {
+            return [];
+        }
+        const candidates = RuntimeJoin.candidateNames(functionName);
+        return fileNodes.filter((node) => NAME_MATCH_KINDS.has(node.kind) && candidates.includes(node.name));
+    }
+    static isMeaningfulName(functionName) {
+        return functionName.length > 0 && functionName.startsWith('(') === false;
+    }
+    static candidateNames(functionName) {
+        const dot = functionName.lastIndexOf('.');
+        if (dot >= 0 && dot < functionName.length - 1) {
+            return [functionName, functionName.slice(dot + 1)];
+        }
+        return [functionName];
+    }
+    /**
+     * Picks the innermost node whose range encloses `line`. Ties on range width
+     * break toward the later-starting node, which is the more deeply nested
+     * declaration. A non-positive line (V8 synthetic frame, or a transpiler that
+     * collapsed line numbers) encloses nothing.
+     */
+    static enclosingNode(nodes, line) {
+        if (line < 1) {
+            return undefined;
+        }
+        let best;
+        let bestSpan = Number.POSITIVE_INFINITY;
+        for (const node of nodes) {
+            if (node.startLine < 1 || node.endLine < node.startLine) {
+                continue;
+            }
+            if (line < node.startLine || line > node.endLine) {
+                continue;
+            }
+            const span = node.endLine - node.startLine;
+            if (span < bestSpan || (span === bestSpan && best !== undefined && node.startLine > best.startLine)) {
+                best = node;
+                bestSpan = span;
+            }
+        }
+        return best;
+    }
+    /**
+     * Maps a profile frame url to a graph `filePath`. Node-internal and empty
+     * urls (`node:`, `(root)`, `(idle)`) resolve to nothing. A url inside `root`
+     * resolves by relative path; otherwise a unique path-suffix match is used so
+     * a graph extracted under a different absolute prefix still attaches.
+     */
+    static resolveFilePath(url, root, byFile, filePaths) {
+        if (url.length === 0 || url.startsWith('node:')) {
+            return undefined;
+        }
+        const absolute = RuntimeJoin.urlToAbsolute(url);
+        if (absolute === undefined) {
+            return byFile.has(url) ? url : undefined;
+        }
+        const normalizedAbsolute = RuntimeJoin.toPosix(absolute);
+        const candidate = RuntimeJoin.toPosix(relative(root, absolute));
+        if (candidate.length > 0 && candidate.startsWith('..') === false && isAbsolute(candidate) === false && byFile.has(candidate)) {
+            return candidate;
+        }
+        let suffixMatch;
+        for (const filePath of filePaths) {
+            if (normalizedAbsolute === filePath || normalizedAbsolute.endsWith(`/${filePath}`)) {
+                if (suffixMatch !== undefined && suffixMatch !== filePath) {
+                    return undefined;
+                }
+                suffixMatch = filePath;
+            }
+        }
+        return suffixMatch;
+    }
+    static urlToAbsolute(url) {
+        if (url.startsWith('file://')) {
+            return fileURLToPath(url);
+        }
+        if (isAbsolute(url)) {
+            return url;
+        }
+        return undefined;
+    }
+    static toPosix(value) {
+        return sep === '/' ? value : value.split(sep).join('/');
+    }
+    static recordDrop(dropped, frame, reason) {
+        const label = RuntimeJoin.dropLabel(frame, reason);
+        const key = `${reason}:${label}`;
+        const group = dropped.get(key) ?? { label, reason, samples: 0, selfMicros: 0 };
+        group.samples += frame.samples;
+        group.selfMicros += frame.selfMicros;
+        dropped.set(key, group);
+    }
+    static dropLabel(frame, reason) {
+        const name = frame.functionName.length > 0 ? frame.functionName : '(anonymous)';
+        if (reason === 'no-file') {
+            return frame.url.length === 0 ? name : `${name} ${frame.url}`;
+        }
+        return `${name} ${frame.url}:${frame.line}`;
+    }
+}
+//# sourceMappingURL=runtime_join.js.map

package/dist/enrich/runtime_join.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime_join.js","sourceRoot":"","sources":["../../src/enrich/runtime_join.ts"],"names":[],"mappings":"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"}

package/dist/extract/api_extractor.d.ts

@@ -0,0 +1,24 @@
+import { SourceFile } from 'ts-morph';
+import { Extraction } from './structural_extractor.js';
+/**
+ * Detects outbound HTTP calls via `fetch(...)` and emits an `ExternalAPI` node for
+ * the called host plus a `CALLS_EXTERNAL` edge from the calling declaration. The
+ * host is taken from a static URL argument (`fetch('https://api.example.com/…')`);
+ * a call whose target is not statically a URL is attributed to a single generic
+ * `(dynamic)` node, so the outbound-I/O call site is still surfaced. Calls to the
+ * same host from one scope collapse to a single counted edge.
+ *
+ * Detection is purely syntactic (no symbol resolution), so it runs in the
+ * structural pass; a project that never calls `fetch` is unchanged. Other HTTP
+ * clients (axios, got, …) are out of scope for now — fetch first (#31 Part 2b).
+ */
+export declare class ApiExtractor {
+    static extract(sourceFile: SourceFile, rootPath: string): Extraction;
+    /** `fetch(...)` — the bare global, or `window` / `globalThis` / `self`.fetch(...). */
+    private static isFetchCall;
+    /** The host of a static URL argument, or {@link DYNAMIC_TARGET} when not statically a URL. */
+    private static targetHost;
+    /** The literal text of a string / no-substitution-template argument, else undefined. */
+    private static staticUrl;
+}
+//# sourceMappingURL=api_extractor.d.ts.map

package/dist/extract/api_extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api_extractor.d.ts","sourceRoot":"","sources":["../../src/extract/api_extractor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,UAAU,EAAc,MAAM,UAAU,CAAC;AAKxD,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAQvD;;;;;;;;;;;GAWG;AACH,qBAAa,YAAY;IACxB,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU;IAmBpE,sFAAsF;IACtF,OAAO,CAAC,MAAM,CAAC,WAAW;IAY1B,8FAA8F;IAC9F,OAAO,CAAC,MAAM,CAAC,UAAU;IAYzB,wFAAwF;IACxF,OAAO,CAAC,MAAM,CAAC,SAAS;CAOxB"}

package/dist/extract/api_extractor.js

@@ -0,0 +1,71 @@
+import { Node, SyntaxKind } from 'ts-morph';
+import { NodeId } from './node_id.js';
+import { ScopeResolver } from './scope_resolver.js';
+/** Receivers on which a `.fetch(...)` call is the WHATWG global rather than a user method. */
+const FETCH_GLOBALS = new Set(['window', 'globalThis', 'self']);
+/** Host used when a fetch target is not a static URL (a variable, a built string, a relative path). */
+const DYNAMIC_TARGET = '(dynamic)';
+/**
+ * Detects outbound HTTP calls via `fetch(...)` and emits an `ExternalAPI` node for
+ * the called host plus a `CALLS_EXTERNAL` edge from the calling declaration. The
+ * host is taken from a static URL argument (`fetch('https://api.example.com/…')`);
+ * a call whose target is not statically a URL is attributed to a single generic
+ * `(dynamic)` node, so the outbound-I/O call site is still surfaced. Calls to the
+ * same host from one scope collapse to a single counted edge.
+ *
+ * Detection is purely syntactic (no symbol resolution), so it runs in the
+ * structural pass; a project that never calls `fetch` is unchanged. Other HTTP
+ * clients (axios, got, …) are out of scope for now — fetch first (#31 Part 2b).
+ */
+export class ApiExtractor {
+    static extract(sourceFile, rootPath) {
+        const nodes = [];
+        const edges = [];
+        const moduleId = NodeId.forModule(sourceFile.getFilePath(), rootPath);
+        for (const call of sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+            if (ApiExtractor.isFetchCall(call.getExpression()) === false) {
+                continue;
+            }
+            const host = ApiExtractor.targetHost(call.getArguments()[0]);
+            const apiId = NodeId.forExternalApi(host);
+            nodes.push({ id: apiId, kind: 'ExternalAPI', name: host, filePath: host });
+            const scopeId = ScopeResolver.enclosingId(call, moduleId, rootPath);
+            edges.push({ id: `CALLS_EXTERNAL:${scopeId}->${apiId}`, kind: 'CALLS_EXTERNAL', from: scopeId, to: apiId });
+        }
+        return { nodes, edges };
+    }
+    /** `fetch(...)` — the bare global, or `window` / `globalThis` / `self`.fetch(...). */
+    static isFetchCall(callee) {
+        if (Node.isIdentifier(callee) === true) {
+            return callee.getText() === 'fetch';
+        }
+        const access = callee.asKind(SyntaxKind.PropertyAccessExpression);
+        if (access === undefined || access.getName() !== 'fetch') {
+            return false;
+        }
+        const target = access.getExpression();
+        return Node.isIdentifier(target) === true && FETCH_GLOBALS.has(target.getText()) === true;
+    }
+    /** The host of a static URL argument, or {@link DYNAMIC_TARGET} when not statically a URL. */
+    static targetHost(argument) {
+        const url = ApiExtractor.staticUrl(argument);
+        if (url === undefined) {
+            return DYNAMIC_TARGET;
+        }
+        try {
+            return new URL(url).host || DYNAMIC_TARGET;
+        }
+        catch {
+            return DYNAMIC_TARGET;
+        }
+    }
+    /** The literal text of a string / no-substitution-template argument, else undefined. */
+    static staticUrl(argument) {
+        const string = argument?.asKind(SyntaxKind.StringLiteral);
+        if (string !== undefined) {
+            return string.getLiteralText();
+        }
+        return argument?.asKind(SyntaxKind.NoSubstitutionTemplateLiteral)?.getLiteralText();
+    }
+}
+//# sourceMappingURL=api_extractor.js.map

package/dist/extract/api_extractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api_extractor.js","sourceRoot":"","sources":["../../src/extract/api_extractor.ts"],"names":[],"mappings":"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"}

package/dist/extract/config_extractor.d.ts

@@ -0,0 +1,22 @@
+import { SourceFile } from 'ts-morph';
+import { Extraction } from './structural_extractor.js';
+/**
+ * Detects configuration reads — `process.env.NAME` and `process.env['NAME']` —
+ * and emits one `ConfigFlag` node per distinct variable plus a `READS_CONFIG`
+ * edge from the enclosing declaration that performs the read. A variable read in
+ * several places collapses to one node (keyed by name) with one counted edge per
+ * reading scope.
+ *
+ * The detection is purely syntactic (no symbol resolution), so it runs in the
+ * structural pass and is always emitted. A project that never touches
+ * `process.env` produces no config nodes or edges, leaving its graph unchanged.
+ */
+export declare class ConfigExtractor {
+    static extract(sourceFile: SourceFile, rootPath: string): Extraction;
+    private static emit;
+    /** Whether a node is the `process.env` member access (`process` identifier, `env` name). */
+    private static isProcessEnv;
+    /** The literal key of `process.env['NAME']`, or undefined when the key is computed. */
+    private static stringArgument;
+}
+//# sourceMappingURL=config_extractor.d.ts.map

package/dist/extract/config_extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config_extractor.d.ts","sourceRoot":"","sources":["../../src/extract/config_extractor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,UAAU,EAAc,MAAM,UAAU,CAAC;AAKxD,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAEvD;;;;;;;;;;GAUG;AACH,qBAAa,eAAe;IAC3B,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU;IAuBpE,OAAO,CAAC,MAAM,CAAC,IAAI;IAiBnB,4FAA4F;IAC5F,OAAO,CAAC,MAAM,CAAC,YAAY;IAS3B,uFAAuF;IACvF,OAAO,CAAC,MAAM,CAAC,cAAc;CAK7B"}