cgraphx 2.0.2 → 2.0.6

package/dist/core/code/engine/core/ingestion/di-extractors/spring.js

@@ -0,0 +1,310 @@
+"use strict";
+/**
+ * Spring dependency-injection field matcher for the generic `di` phase.
+ *
+ * Recognizes the fields Spring's container fills via collect-all-implementers
+ * collection injection: when a Java class declares a field carrying an
+ * injection annotation (`@Autowired` or `@Inject`) typed as `List<T>`,
+ * `Set<T>`, `Collection<T>`, or `Map<K,T>`, the container injects EVERY bean
+ * implementing interface `T`. The matcher reports the element type name `T`
+ * plus a human-readable reason naming the collection wrapper and the
+ * annotation that gated the match; the shared `di` phase turns that into
+ * `INJECTS` edges.
+ *
+ * The injection annotation is a hard precondition: a plain (non-annotated)
+ * collection field is never injected by the container and produces no match.
+ * `@Resource` (JSR-250) is DELIBERATELY excluded: it resolves by bean NAME
+ * first (defaulting to the field name), which injects a single named
+ * collection bean — the opposite of the collect-all-implementers fan-out
+ * INJECTS models. Including it would emit false edges.
+ *
+ * Matching happens on `rawDeclaredType` (the verbatim type text, generics
+ * preserved) — NOT `declaredType`, which is generics-stripped by design
+ * (`List<Shape>` → `List`) and can never match the collection patterns.
+ *
+ * Accepted type shapes (after whitespace normalization — internal runs of
+ * whitespace, including newlines from multi-line declarations, collapse to a
+ * single space):
+ * - `List<T>` / `Set<T>` / `Collection<T>` — element `T`.
+ * - `Map<K, T>` — element is the VALUE type `T`; the key `K` is irrelevant
+ *   for DI resolution and may itself be generic (`Map<Pair<A,B>, T>` — the
+ *   top-level-comma split is bracket-depth-aware, so nested commas in the
+ *   key never bleed into the element).
+ * - Bounded wildcards `List<? extends T>` / `List<? super T>` — element `T`
+ *   (both are idiomatic Spring collection injection; the container still
+ *   collects every implementer of `T`).
+ * - Package-qualified wrappers `java.util.List<T>` — the wrapper is
+ *   recognized by its LAST dotted segment. The ELEMENT keeps its dots
+ *   (`List<com.a.Shape>` → `com.a.Shape`): dotted element names resolve via
+ *   `qualifiedName` downstream in the `di` phase.
+ *
+ * Documented REJECTIONS (parse returns `null` — no INJECTS edges):
+ * - `Map<String, List<IFoo>>` — the element itself is generic; a nested
+ *   generic is not resolvable as a single interface.
+ * - `List<?>` — unbounded wildcard; there is no element type to fan out to.
+ * - Arrays: `IFoo[]`, `List<IFoo>[]`, `List<IFoo[]>` — array injection is
+ *   not the collect-all-implementers shape INJECTS models.
+ * - Non-collection types (`IFoo`, `Optional<IFoo>`, …) and wrong generic
+ *   arity (`Map<String>`, `List<A, B>`).
+ * - Anything whose element is not a plain (possibly dotted) Java type name —
+ *   this makes the parser fail closed on unanticipated syntax. In particular
+ *   Java block comments inside the generic arguments (a `/* ... ` comment
+ *   between `<` and the element) are NOT stripped and fail closed —
+ *   acceptable.
+ *
+ * Registered for Java and Kotlin in `./index.ts` (`DI_RESOLVERS`); language
+ * routing is the registry's job, so the matcher itself never reads
+ * `node.properties.language`. Kotlin's AST-backed class metadata is the
+ * primary path because Kotlin Property extraction intentionally exposes less
+ * annotation/type syntax than Java's legacy field contract.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.springDiResolver = exports.springDiFieldMatcher = exports.SPRING_DI_CAPTURED_FIELD_PROPERTY = exports.SPRING_DI_PROVIDER_PROPERTY = exports.SPRING_DI_INJECTION_SITES_PROPERTY = void 0;
+exports.parseSpringCollectionType = parseSpringCollectionType;
+exports.parseSpringInjectionType = parseSpringInjectionType;
+const env_js_1 = require("../utils/env.js");
+const logger_js_1 = require("../../logger.js");
+/**
+ * Annotations that trigger Spring's collect-all-implementers collection
+ * injection. `@Resource` is deliberately absent — JSR-250 resolves by bean
+ * NAME first (defaulting to the field name), injecting a single named
+ * collection bean rather than fanning out to every implementer, so an
+ * INJECTS fan-out for it would be a false edge.
+ */
+const INJECTION_ANNOTATIONS = new Set(['@Autowired', '@Inject']);
+/** Collection wrappers whose generic element Spring fans out to every
+ *  implementer. `Map` is special-cased for arity (2 args, element = value). */
+const COLLECTION_WRAPPERS = new Set(['List', 'Set', 'Collection', 'Map']);
+/** Bounded-wildcard prefixes stripped from the element position (single-spaced
+ *  — the input is whitespace-normalized before these are checked). */
+const WILDCARD_EXTENDS_PREFIX = '? extends ';
+const WILDCARD_SUPER_PREFIX = '? super ';
+/** A plain (possibly dotted) Java type name — the only element shape the
+ *  parser accepts. Everything else (wildcards, arrays, comments, stray
+ *  punctuation) fails closed. */
+const JAVA_TYPE_NAME_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]*(?:\.[A-Za-z_$][A-Za-z0-9_$]*)*$/;
+/** Ephemeral Class-node property populated by Java's post-resolution Spring
+ * metadata hook. It is consumed in the same pipeline run before persistence. */
+exports.SPRING_DI_INJECTION_SITES_PROPERTY = 'springDiInjectionSites';
+/** Ephemeral Class-node property carrying Spring bean names / @Primary. */
+exports.SPRING_DI_PROVIDER_PROPERTY = 'springDiProvider';
+/** Marker placed on Property nodes whose richer AST-backed field fact was
+ * attached to the owning Class, suppressing the legacy collection fallback. */
+exports.SPRING_DI_CAPTURED_FIELD_PROPERTY = 'springDiCapturedField';
+/**
+ * Split a generic-argument list on TOP-LEVEL commas only, tracking `<`/`>`
+ * bracket depth so nested generics (e.g. the `Pair<A,B>` key in
+ * `Map<Pair<A,B>, IFoo>`) never split mid-argument.
+ *
+ * @returns the top-level argument segments (untrimmed), or `null` when the
+ *          brackets are unbalanced (fail closed on malformed input).
+ */
+function splitTopLevelGenericArgs(inner) {
+    const args = [];
+    let depth = 0;
+    let segmentStart = 0;
+    for (let i = 0; i < inner.length; i++) {
+        const ch = inner[i];
+        if (ch === '<') {
+            depth++;
+        }
+        else if (ch === '>') {
+            depth--;
+            if (depth < 0)
+                return null;
+        }
+        else if (ch === ',' && depth === 0) {
+            args.push(inner.slice(segmentStart, i));
+            segmentStart = i + 1;
+        }
+    }
+    if (depth !== 0)
+        return null;
+    args.push(inner.slice(segmentStart));
+    return args;
+}
+/**
+ * Extract the injected bean type name from one (whitespace-normalized)
+ * generic-argument segment: strip a bounded-wildcard prefix, then require a
+ * plain dotted Java type name.
+ *
+ * @returns the element type name, or `null` for unbounded wildcards, nested
+ *          generics, arrays, and any other non-type-name shape (fail closed).
+ */
+function parseElementTypeName(segment) {
+    let element = segment.trim();
+    // Bounded wildcards are idiomatic collection injection: the container
+    // still collects every implementer of the bound.
+    if (element.startsWith(WILDCARD_EXTENDS_PREFIX)) {
+        element = element.slice(WILDCARD_EXTENDS_PREFIX.length);
+    }
+    else if (element.startsWith(WILDCARD_SUPER_PREFIX)) {
+        element = element.slice(WILDCARD_SUPER_PREFIX.length);
+    }
+    // Final gate: a plain (possibly dotted) type name. Rejects nested generics
+    // (`Map<String, List<IFoo>>` — not resolvable as a single interface),
+    // arrays (`List<IFoo[]>` — not the fan-out shape INJECTS models), the
+    // unbounded wildcard `?`, un-stripped comments, and any other residue —
+    // all documented rejections; fail closed.
+    if (!JAVA_TYPE_NAME_PATTERN.test(element))
+        return null;
+    return element;
+}
+/**
+ * Parse a Spring DI collection field's raw declared type (verbatim source
+ * text, generics preserved) and return the injected bean type name.
+ *
+ * Whitespace-normalizes first (raw tree-sitter `.text` can span lines), then
+ * recognizes the wrapper by the LAST dotted segment before the first `<`
+ * (so `java.util.List<IFoo>` works), depth-aware-splits the generic argument
+ * list, and validates the element position. See the module docstring for the
+ * full accepted/rejected shape inventory.
+ *
+ * @returns the collection wrapper name + element type name, or `null` when
+ *          the raw declared type is not a recognized Spring collection shape.
+ */
+function parseSpringCollectionType(rawDeclaredType) {
+    // Collapse ALL internal whitespace runs (spaces, tabs, newlines from
+    // multi-line declarations) to single spaces, then trim the ends.
+    const normalized = rawDeclaredType.replace(/\s+/g, ' ').trim();
+    const openIndex = normalized.indexOf('<');
+    // No generic argument list, or trailing residue after the closing `>`
+    // (e.g. the array suffix in `List<IFoo>[]`) — not a collection injection.
+    if (openIndex === -1 || !normalized.endsWith('>'))
+        return null;
+    // Wrapper = last dotted segment of the pre-`<` text: strips a package
+    // qualifier from the WRAPPER only (`java.util.List` → `List`).
+    const wrapperPath = normalized.slice(0, openIndex).trim();
+    const wrapperSegments = wrapperPath.split('.');
+    const wrapper = wrapperSegments[wrapperSegments.length - 1];
+    if (!COLLECTION_WRAPPERS.has(wrapper))
+        return null;
+    const inner = normalized.slice(openIndex + 1, normalized.length - 1);
+    const args = splitTopLevelGenericArgs(inner);
+    if (args === null)
+        return null;
+    // List/Set/Collection take exactly one type argument; Map exactly two,
+    // and the injected bean type is the VALUE (2nd argument) — the key is
+    // irrelevant for DI resolution.
+    const expectedArity = wrapper === 'Map' ? 2 : 1;
+    if (args.length !== expectedArity)
+        return null;
+    const elementTypeName = parseElementTypeName(args[expectedArity - 1]);
+    if (elementTypeName === null)
+        return null;
+    return { collectionType: wrapper, elementTypeName };
+}
+/** Parse either a supported collect-all type or a standard single bean type. */
+function parseSpringInjectionType(rawDeclaredType) {
+    const collection = parseSpringCollectionType(rawDeclaredType);
+    if (collection !== null) {
+        return {
+            targetTypeName: collection.elementTypeName,
+            cardinality: 'collection',
+            displayType: `${collection.collectionType}<${collection.elementTypeName}>`,
+        };
+    }
+    const normalized = rawDeclaredType.replace(/\s+/g, '').trim();
+    if (!JAVA_TYPE_NAME_PATTERN.test(normalized))
+        return null;
+    return { targetTypeName: normalized, cardinality: 'single', displayType: normalized };
+}
+/**
+ * Match a `Property` node against Spring's collection-injection shape.
+ *
+ * Returns the parsed match (with a Spring-specific human-readable `reason`
+ * payload) or `null` when the field is not container-injected.
+ */
+const springDiFieldMatcher = (node) => {
+    // Injection-annotation gate: only fields the container actually
+    // injects (@Autowired / @Inject) are candidates. Plain collection
+    // fields are never injected; @Resource is deliberately excluded
+    // (by-name-first semantics — see INJECTION_ANNOTATIONS).
+    const matchedAnnotation = node.properties.annotations?.find((a) => INJECTION_ANNOTATIONS.has(a));
+    if (matchedAnnotation === undefined)
+        return null;
+    // Match on rawDeclaredType ONLY — no `?? declaredType` fallback:
+    // production `declaredType` is generics-stripped by design, so a
+    // fallback can never match real data and would only mask plumbing
+    // regressions as quiet no-ops.
+    const rawDeclaredType = node.properties.rawDeclaredType;
+    if (!rawDeclaredType) {
+        // An injection-annotated field with NO rawDeclaredType means the
+        // extraction plumbing broke its contract (U1 threads the raw type
+        // wherever annotations are threaded) — surface it, don't silently drop.
+        if (env_js_1.isDev) {
+            logger_js_1.logger.warn(`Spring DI: annotated field '${node.properties.name}' (${node.properties.filePath}) has no rawDeclaredType — extraction plumbing contract breach; skipping`);
+        }
+        return null;
+    }
+    const parsed = parseSpringCollectionType(rawDeclaredType);
+    if (!parsed)
+        return null;
+    return {
+        elementTypeName: parsed.elementTypeName,
+        // Honest reason: states the annotation actually found on the field and
+        // the collection wrapper it gated. Framework specifics live HERE, in the
+        // payload — never in the phase.
+        reason: `Spring DI: ${matchedAnnotation} ${parsed.collectionType}<${parsed.elementTypeName}>`,
+    };
+};
+exports.springDiFieldMatcher = springDiFieldMatcher;
+function isInjectionMatch(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const match = value;
+    const namedSelection = match.namedSelection;
+    return (typeof match.targetTypeName === 'string' &&
+        (match.cardinality === 'single' || match.cardinality === 'collection') &&
+        typeof match.reason === 'string' &&
+        (match.edgeSource === undefined ||
+            match.edgeSource === 'owner-class' ||
+            match.edgeSource === 'site') &&
+        (namedSelection === undefined ||
+            (typeof namedSelection === 'object' &&
+                namedSelection !== null &&
+                typeof namedSelection.name === 'string' &&
+                typeof namedSelection.reason === 'string' &&
+                (namedSelection.fallbackToType === undefined ||
+                    typeof namedSelection.fallbackToType === 'boolean'))));
+}
+function isProviderMatch(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const provider = value;
+    return (Array.isArray(provider.names) &&
+        provider.names.every((name) => typeof name === 'string') &&
+        (provider.providedTypeName === undefined || typeof provider.providedTypeName === 'string') &&
+        (provider.declaredByNodeId === undefined || typeof provider.declaredByNodeId === 'string') &&
+        (provider.preferenceReason === undefined || typeof provider.preferenceReason === 'string'));
+}
+/** JVM/Spring resolver registered behind the framework-neutral DI seam. */
+exports.springDiResolver = {
+    matchInjectionSites(node) {
+        const matches = [];
+        // Preserve the existing Property-node collection contract for hand-built
+        // graphs and for compatibility with pre-#2414 extraction fixtures.
+        if (node.label === 'Property' && node.properties[exports.SPRING_DI_CAPTURED_FIELD_PROPERTY] !== true) {
+            const field = (0, exports.springDiFieldMatcher)(node);
+            if (field !== null) {
+                matches.push({
+                    targetTypeName: field.elementTypeName,
+                    cardinality: 'collection',
+                    reason: field.reason,
+                });
+            }
+        }
+        const attached = node.properties[exports.SPRING_DI_INJECTION_SITES_PROPERTY];
+        if (Array.isArray(attached)) {
+            for (const candidate of attached) {
+                if (isInjectionMatch(candidate))
+                    matches.push(candidate);
+            }
+        }
+        return matches;
+    },
+    matchProvider(node) {
+        const attached = node.properties[exports.SPRING_DI_PROVIDER_PROPERTY];
+        return isProviderMatch(attached) ? attached : null;
+    },
+};

package/dist/core/code/engine/core/ingestion/emit-references.js

@@ -0,0 +1,244 @@
+"use strict";
+/**
+ * Phase 5 of the RFC #909 ingestion lifecycle: drain `ReferenceIndex`
+ * into the knowledge graph as labeled edges with `confidence` and
+ * `evidence` properties (Ring 2 PKG #925).
+ *
+ * The resolution phase (future PR) writes `Reference` records into
+ * `model.scopes.referenceSites`-derived `ReferenceIndex`; this module
+ * materializes those records as `GraphRelationship`s via
+ * `graph.addRelationship`. Every emitted edge carries:
+ *
+ *   - `type`: one of `'CALLS' | 'ACCESSES' | 'INHERITS' | 'USES'`
+ *     (mapped from `Reference.kind` — `'read'` and `'write'` both route
+ *     to `ACCESSES`; `'type-reference'` and `'import-use'` route to
+ *     `USES`; `'call'` stays `CALLS`; `'inherits'` stays `INHERITS`).
+ *   - `confidence`: the pre-computed confidence from the Reference record.
+ *   - `reason`: human-readable summary (`"scope-resolution: call | confidence 0.75"`).
+ *   - `evidence`: the full `ResolutionEvidence[]` trace — additive graph
+ *     property (see `GraphRelationship.evidence` in cgraph-shared),
+ *     so queries that don't know about it are unaffected.
+ *   - `step`: carries the reference's access-kind discriminant when
+ *     available (`1` for read, `2` for write) so `ACCESSES` edges retain
+ *     the read/write distinction without forcing a new edge type.
+ *
+ * ## Optional scope-tree flush
+ *
+ * When `INGESTION_EMIT_SCOPES=1` is set, this module also emits:
+ *
+ *   - `Scope` nodes for every `Scope` in the tree
+ *   - `CONTAINS` edges from parent scope to child scope
+ *   - `DEFINES` edges from scope to its `ownedDefs` members
+ *   - `IMPORTS` edges from scope to `targetModuleScope` of each finalized
+ *     `ImportEdge` that carries one
+ *
+ * Off by default — existing queries that don't know about `Scope` nodes
+ * continue to work, and the storage cost is opt-in.
+ *
+ * ## Source-of-truth: the caller def for a reference
+ *
+ * A `Reference` says "some code inside `fromScope` references `toDef`".
+ * The graph wants `(callerNodeId, calleeNodeId)`. We resolve the caller
+ * by walking up the scope tree from `fromScope` until we find a scope
+ * whose `ownedDefs` contains a Function-like def. If no such ancestor
+ * exists, the edge is attributed to the first def owned by the innermost
+ * ancestor scope, and if THAT produces nothing either the edge is
+ * skipped (with a count returned in `EmitStats.skippedNoCaller`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emitReferencesToGraph = emitReferencesToGraph;
+exports.emitScopeGraph = emitScopeGraph;
+const line_base_js_1 = require("./utils/line-base.js");
+/**
+ * Drain `referenceIndex.bySourceScope` into graph edges.
+ *
+ * The scope-tree flush is controlled separately by
+ * `INGESTION_EMIT_SCOPES` — callers can run `emitReferencesToGraph`
+ * without scope-node emission or layer the two calls as needed.
+ */
+function emitReferencesToGraph(input) {
+    const { graph, scopes, referenceIndex } = input;
+    const sourceLabel = input.sourceLabel ?? 'scope-resolution';
+    let edgesEmitted = 0;
+    let skippedNoCaller = 0;
+    let skippedMissingTarget = 0;
+    for (const [fromScope, refs] of referenceIndex.bySourceScope) {
+        for (const ref of refs) {
+            const targetDef = scopes.defs.get(ref.toDef);
+            if (targetDef === undefined) {
+                skippedMissingTarget++;
+                continue;
+            }
+            const callerId = resolveCallerNodeId(fromScope, scopes);
+            if (callerId === undefined) {
+                skippedNoCaller++;
+                continue;
+            }
+            graph.addRelationship(buildRelationship(ref, callerId, targetDef, sourceLabel));
+            edgesEmitted++;
+        }
+    }
+    const scopeStats = isScopeEmissionEnabled()
+        ? emitScopeGraph({ graph, scopes })
+        : { scopeNodesEmitted: 0, scopeEdgesEmitted: 0 };
+    return { edgesEmitted, skippedNoCaller, skippedMissingTarget, ...scopeStats };
+}
+/**
+ * Emit `Scope` nodes + `CONTAINS`/`DEFINES`/`IMPORTS` edges representing
+ * the lexical scope tree itself. Skipped unless `INGESTION_EMIT_SCOPES=1`
+ * at the public entry point; exported here for tests that want to
+ * exercise the path directly.
+ */
+function emitScopeGraph(input) {
+    const { graph, scopes } = input;
+    let scopeNodesEmitted = 0;
+    let scopeEdgesEmitted = 0;
+    for (const scope of scopes.scopeTree.byId.values()) {
+        graph.addNode({
+            id: scope.id,
+            label: 'CodeElement', // the generic bucket for non-symbol graph nodes
+            properties: {
+                name: scope.kind,
+                filePath: scope.filePath,
+                startLine: (0, line_base_js_1.toZeroBasedLine)(scope.range.startLine),
+                endLine: (0, line_base_js_1.toZeroBasedLine)(scope.range.endLine),
+                description: `Scope: ${scope.kind}`,
+            },
+        });
+        scopeNodesEmitted++;
+        if (scope.parent !== null) {
+            graph.addRelationship({
+                id: `rel:contains:${scope.parent}->${scope.id}`,
+                sourceId: scope.parent,
+                targetId: scope.id,
+                type: 'CONTAINS',
+                confidence: 1,
+                reason: 'scope-tree parent/child',
+            });
+            scopeEdgesEmitted++;
+        }
+        for (const def of scope.ownedDefs) {
+            graph.addRelationship({
+                id: `rel:defines:${scope.id}->${def.nodeId}`,
+                sourceId: scope.id,
+                targetId: def.nodeId,
+                type: 'DEFINES',
+                confidence: 1,
+                reason: 'scope.ownedDefs',
+            });
+            scopeEdgesEmitted++;
+        }
+    }
+    for (const [scopeId, edges] of scopes.imports) {
+        for (const edge of edges) {
+            if (edge.targetModuleScope === undefined)
+                continue;
+            graph.addRelationship({
+                id: `rel:imports:${scopeId}->${edge.targetModuleScope}:${edge.localName}`,
+                sourceId: scopeId,
+                targetId: edge.targetModuleScope,
+                type: 'IMPORTS',
+                confidence: edge.linkStatus === 'unresolved' ? 0.5 : 1,
+                reason: `import ${edge.kind} ${edge.localName}`,
+            });
+            scopeEdgesEmitted++;
+        }
+    }
+    return { scopeNodesEmitted, scopeEdgesEmitted };
+}
+// ─── Internal ───────────────────────────────────────────────────────────────
+/** Accepted truthy values for `INGESTION_EMIT_SCOPES`. */
+const TRUTHY = new Set(['true', '1', 'yes']);
+function isScopeEmissionEnabled() {
+    const raw = process.env['INGESTION_EMIT_SCOPES'];
+    if (raw === undefined)
+        return false;
+    return TRUTHY.has(raw.trim().toLowerCase());
+}
+/**
+ * Walk up from `startScope` looking for the first ancestor scope whose
+ * `ownedDefs` contains a Function-like def (Function / Method /
+ * Constructor). Fall back to the innermost ancestor's first `ownedDef`
+ * if none is found; return `undefined` if all ancestors have no defs.
+ */
+function resolveCallerNodeId(startScope, scopes) {
+    const tree = scopes.scopeTree;
+    let current = startScope;
+    const visited = new Set();
+    let firstOwnedFallback;
+    while (current !== null) {
+        if (visited.has(current))
+            break;
+        visited.add(current);
+        const scope = tree.getScope(current);
+        if (scope === undefined)
+            break;
+        // Prefer a Function-like owner.
+        const fnDef = scope.ownedDefs.find((d) => isFunctionLike(d.type));
+        if (fnDef !== undefined)
+            return fnDef.nodeId;
+        // Stash the first owned def we see as a conservative fallback.
+        if (firstOwnedFallback === undefined && scope.ownedDefs.length > 0) {
+            firstOwnedFallback = scope.ownedDefs[0].nodeId;
+        }
+        current = scope.parent;
+    }
+    return firstOwnedFallback;
+}
+function isFunctionLike(type) {
+    return type === 'Function' || type === 'Method' || type === 'Constructor';
+}
+function buildRelationship(ref, callerId, targetDef, sourceLabel) {
+    const type = mapKindToType(ref.kind);
+    const reason = `${sourceLabel}: ${ref.kind} | confidence ${ref.confidence.toFixed(3)}`;
+    // `step` encodes read/write discriminator for ACCESSES edges (1=read, 2=write).
+    // Other kinds omit `step`.
+    const step = ref.kind === 'read' ? 1 : ref.kind === 'write' ? 2 : undefined;
+    return {
+        id: `rel:${type}:${callerId}->${targetDef.nodeId}:${ref.atRange.startLine}:${ref.atRange.startCol}`,
+        sourceId: callerId,
+        targetId: targetDef.nodeId,
+        type,
+        confidence: ref.confidence,
+        reason,
+        evidence: ref.evidence.map(serializeEvidence),
+        ...(step !== undefined ? { step } : {}),
+    };
+}
+/**
+ * Map a `Reference.kind` to an existing `RelationshipType`. Read/write
+ * both fold into `ACCESSES`; `type-reference`, `import-use`, and `macro`
+ * all fold into `USES`. This keeps the graph schema additive — no new
+ * RelationshipType values are introduced by this module.
+ *
+ * `macro` folds into `USES` (not `CALLS`) deliberately: a macro
+ * invocation targets a `Macro` node, not a callable function, so keeping
+ * it out of the `CALLS` keyspace preserves the invariant that `CALLS`
+ * edges denote function/method dispatch.
+ */
+function mapKindToType(kind) {
+    switch (kind) {
+        case 'call':
+            return 'CALLS';
+        case 'read':
+        case 'write':
+            return 'ACCESSES';
+        case 'inherits':
+            return 'INHERITS';
+        case 'type-reference':
+        case 'import-use':
+        case 'macro':
+        // value-ref: function registered as an object-literal property value —
+        // a reference, not an invocation; CALLS are synthesized separately by
+        // the property-dispatch pass (#2437).
+        case 'value-ref':
+            return 'USES';
+    }
+}
+function serializeEvidence(e) {
+    return {
+        kind: e.kind,
+        weight: e.weight,
+        ...(e.note !== undefined ? { note: e.note } : {}),
+    };
+}