ts-knowledge-graph 0.1.2 → 0.1.4

package/dist/enrich/runtime_join.d.ts

@@ -0,0 +1,100 @@
+import { FrameSample } 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;
+};
+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;
+    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":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,yDAAyD;AACzD,MAAM,MAAM,iBAAiB,GAAG;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,+DAA+D;AAC/D,MAAM,MAAM,kBAAkB,GAAG;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,8EAA8E;AAC9E,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;AAExC;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC/B,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAC9C,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,iBAAiB,EAAE,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAChC,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;CACb,CAAC;AAYF,qBAAa,WAAW;IACvB;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,IAAI,CACV,KAAK,EAAE,iBAAiB,EAAE,EAC1B,MAAM,EAAE,WAAW,EAAE,EACrB,OAAO,EAAE,kBAAkB,GACzB,iBAAiB;IA4DpB,OAAO,CAAC,MAAM,CAAC,WAAW;IAa1B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,WAAW;IAmB1B;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,WAAW;IAQ1B,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAI/B,OAAO,CAAC,MAAM,CAAC,cAAc;IAQ7B;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;IAsB5B;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe;IAgC9B,OAAO,CAAC,MAAM,CAAC,aAAa;IAU5B,OAAO,CAAC,MAAM,CAAC,OAAO;IAItB,OAAO,CAAC,MAAM,CAAC,UAAU;IAazB,OAAO,CAAC,MAAM,CAAC,SAAS;CAOxB"}

package/dist/enrich/runtime_join.js

@@ -0,0 +1,227 @@
+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),
+        };
+    }
+    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"}

package/dist/extract/config_extractor.js

@@ -0,0 +1,61 @@
+import { Node, SyntaxKind } from 'ts-morph';
+import { NodeId } from './node_id.js';
+import { ScopeResolver } from './scope_resolver.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 class ConfigExtractor {
+    static extract(sourceFile, rootPath) {
+        const nodes = [];
+        const edges = [];
+        const moduleId = NodeId.forModule(sourceFile.getFilePath(), rootPath);
+        for (const access of sourceFile.getDescendantsOfKind(SyntaxKind.PropertyAccessExpression)) {
+            if (ConfigExtractor.isProcessEnv(access.getExpression()) === true) {
+                ConfigExtractor.emit(access, access.getName(), moduleId, rootPath, nodes, edges);
+            }
+        }
+        for (const access of sourceFile.getDescendantsOfKind(SyntaxKind.ElementAccessExpression)) {
+            if (ConfigExtractor.isProcessEnv(access.getExpression()) === false) {
+                continue;
+            }
+            const name = ConfigExtractor.stringArgument(access);
+            if (name !== undefined) {
+                ConfigExtractor.emit(access, name, moduleId, rootPath, nodes, edges);
+            }
+        }
+        return { nodes, edges };
+    }
+    static emit(access, name, moduleId, rootPath, nodes, edges) {
+        if (name === '') {
+            return;
+        }
+        const flagId = NodeId.forConfigFlag(name);
+        nodes.push({ id: flagId, kind: 'ConfigFlag', name, filePath: 'process.env' });
+        const scopeId = ScopeResolver.enclosingId(access, moduleId, rootPath);
+        edges.push({ id: `READS_CONFIG:${scopeId}->${flagId}`, kind: 'READS_CONFIG', from: scopeId, to: flagId });
+    }
+    /** Whether a node is the `process.env` member access (`process` identifier, `env` name). */
+    static isProcessEnv(node) {
+        const access = node.asKind(SyntaxKind.PropertyAccessExpression);
+        if (access === undefined || access.getName() !== 'env') {
+            return false;
+        }
+        const target = access.getExpression();
+        return Node.isIdentifier(target) === true && target.getText() === 'process';
+    }
+    /** The literal key of `process.env['NAME']`, or undefined when the key is computed. */
+    static stringArgument(access) {
+        const element = access.asKind(SyntaxKind.ElementAccessExpression);
+        const literal = element?.getArgumentExpression()?.asKind(SyntaxKind.StringLiteral);
+        return literal?.getLiteralText();
+    }
+}
+//# sourceMappingURL=config_extractor.js.map

package/dist/extract/config_extractor.js.map

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

package/dist/extract/endpoint_extractor.d.ts

@@ -0,0 +1,36 @@
+import { SourceFile } from 'ts-morph';
+import { Extraction } from './structural_extractor.js';
+/**
+ * Detects HTTP route registrations in the Express/Fastify style —
+ * `app.get('/path', handler)`, `router.post('/path', mw, handler)` — and emits an
+ * `Endpoint` node (keyed by method + path) plus a `HANDLES` edge from the endpoint
+ * to the function that handles it.
+ *
+ * A route is recognised syntactically: the callee is `<obj>.<verb>` for an HTTP
+ * verb, the first argument is a string-literal path, and the last argument is a
+ * handler — an inline function, or a name/member that resolves to an in-project
+ * callable. Resolving the named handler is why this runs in the semantic pass; an
+ * inline handler yields the `Endpoint` node alone (it has no declaration to point
+ * at).
+ *
+ * The match is a heuristic (it does not prove `obj` is an Express app), but the
+ * verb + string path + resolvable-handler combination is specific, so a project
+ * with no such call sites is unchanged. Other routers (Nest decorators, …) are out
+ * of scope for now — Express/Fastify first (#31 Part 3).
+ */
+export declare class EndpointExtractor {
+    static extract(sourceFile: SourceFile, rootPath: string): Extraction;
+    private static extractRoute;
+    /**
+     * Classifies the last argument of a route call. An inline function is a valid
+     * handler with no node to point at; a name/member that resolves to an in-project
+     * callable is a valid handler whose emitted declaration becomes the `HANDLES`
+     * target; anything else means this is not a route.
+     */
+    private static classifyHandler;
+    /** Resolves a handler name/member to the in-project function, method, or function-valued variable it refers to. */
+    private static resolveCallable;
+    private static resolve;
+    private static inProject;
+}
+//# sourceMappingURL=endpoint_extractor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint_extractor.d.ts","sourceRoot":"","sources":["../../src/extract/endpoint_extractor.ts"],"names":[],"mappings":"AACA,OAAO,EAAwB,UAAU,EAAc,MAAM,UAAU,CAAC;AAKxE,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAQvD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,iBAAiB;IAC7B,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU;IASpE,OAAO,CAAC,MAAM,CAAC,YAAY;IAoC3B;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe;IAc9B,mHAAmH;IACnH,OAAO,CAAC,MAAM,CAAC,eAAe;IAkB9B,OAAO,CAAC,MAAM,CAAC,OAAO;IAMtB,OAAO,CAAC,MAAM,CAAC,SAAS;CAKxB"}