@optave/codegraph 3.11.1 → 3.12.0

package/src/extractors/kotlin.ts

@@ -102,7 +102,7 @@ function collectKotlinEnumEntries(node: TreeSitterNode): SubDeclaration[] {
   if (!body) return entries;
   for (let i = 0; i < body.childCount; i++) {
     const child = body.child(i);
-    if (!child || child.type !== 'enum_entry') continue;
+    if (child?.type !== 'enum_entry') continue;
     const entryName = findChild(child, 'simple_identifier');
     if (entryName) {
       entries.push({
@@ -122,7 +122,7 @@ function collectKotlinProperties(node: TreeSitterNode): SubDeclaration[] {
   if (!body) return props;
   for (let i = 0; i < body.childCount; i++) {
     const child = body.child(i);
-    if (!child || child.type !== 'property_declaration') continue;
+    if (child?.type !== 'property_declaration') continue;
     const varDecl = findChild(child, 'variable_declaration');
     if (!varDecl) continue;
     const id = findChild(varDecl, 'simple_identifier');
@@ -144,7 +144,7 @@ function collectKotlinMethods(node: TreeSitterNode, className: string, ctx: Extr
   if (!body) return;
   for (let i = 0; i < body.childCount; i++) {
     const child = body.child(i);
-    if (!child || child.type !== 'function_declaration') continue;
+    if (child?.type !== 'function_declaration') continue;
     const methName = findChild(child, 'simple_identifier');
     if (methName) {
       const params = extractKotlinParameters(child);
@@ -168,7 +168,7 @@ function collectKotlinInheritance(
 ): void {
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
-    if (!child || child.type !== 'delegation_specifier') continue;
+    if (child?.type !== 'delegation_specifier') continue;
 
     // constructor_invocation > user_type > type_identifier (extends)
     const ctorInvocation = findChild(child, 'constructor_invocation');
@@ -294,7 +294,7 @@ function extractKotlinParameters(funcNode: TreeSitterNode): SubDeclaration[] {
   if (!paramList) return params;
   for (let i = 0; i < paramList.childCount; i++) {
     const param = paramList.child(i);
-    if (!param || param.type !== 'parameter') continue;
+    if (param?.type !== 'parameter') continue;
     const nameNode = findChild(param, 'simple_identifier');
     if (nameNode) {
       params.push({ name: nameNode.text, kind: 'parameter', line: param.startPosition.row + 1 });

package/src/extractors/lua.ts

@@ -90,7 +90,7 @@ function extractLuaParams(funcNode: TreeSitterNode): SubDeclaration[] {
 
   for (let i = 0; i < paramList.childCount; i++) {
     const param = paramList.child(i);
-    if (!param || param.type !== 'identifier') continue;
+    if (param?.type !== 'identifier') continue;
     params.push({ name: param.text, kind: 'parameter', line: param.startPosition.row + 1 });
   }
   return params;

package/src/extractors/objc.ts

@@ -468,7 +468,7 @@ function extractPropertyName(propNode: TreeSitterNode): string | null {
   if (!structDecl) return null;
   for (let i = 0; i < structDecl.childCount; i++) {
     const child = structDecl.child(i);
-    if (!child || child.type !== 'struct_declarator') continue;
+    if (child?.type !== 'struct_declarator') continue;
     const id = findIdentifierDeep(child);
     if (id) return id.text;
   }
@@ -494,7 +494,7 @@ function extractMethodParams(methodNode: TreeSitterNode): SubDeclaration[] {
   const params: SubDeclaration[] = [];
   for (let i = 0; i < methodNode.childCount; i++) {
     const child = methodNode.child(i);
-    if (!child || child.type !== 'method_parameter') continue;
+    if (child?.type !== 'method_parameter') continue;
     let nameNode: TreeSitterNode | null = null;
     for (let j = 0; j < child.childCount; j++) {
       const inner = child.child(j);
@@ -516,7 +516,7 @@ function extractCParams(paramListNode: TreeSitterNode | null): SubDeclaration[]
   if (!paramListNode) return params;
   for (let i = 0; i < paramListNode.childCount; i++) {
     const param = paramListNode.child(i);
-    if (!param || param.type !== 'parameter_declaration') continue;
+    if (param?.type !== 'parameter_declaration') continue;
     const nameNode = param.childForFieldName('declarator');
     if (nameNode) {
       const name = unwrapObjCDeclaratorName(nameNode);

package/src/extractors/ocaml.ts

@@ -168,7 +168,7 @@ function handleOCamlTypeDef(node: TreeSitterNode, ctx: ExtractorOutput): void {
   // type_definition contains one or more type_bindings
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
-    if (!child || child.type !== 'type_binding') continue;
+    if (child?.type !== 'type_binding') continue;
 
     const nameNode =
       child.childForFieldName('name') ||

package/src/extractors/php.ts

@@ -36,7 +36,7 @@ function extractPhpParameters(fnNode: TreeSitterNode): SubDeclaration[] {
 function extractPhpProperties(member: TreeSitterNode, children: SubDeclaration[]): void {
   for (let j = 0; j < member.childCount; j++) {
     const el = member.child(j);
-    if (!el || el.type !== 'property_element') continue;
+    if (el?.type !== 'property_element') continue;
     const varNode = findChild(el, 'variable_name');
     if (varNode) {
       children.push({
@@ -53,7 +53,7 @@ function extractPhpProperties(member: TreeSitterNode, children: SubDeclaration[]
 function extractPhpConstants(member: TreeSitterNode, children: SubDeclaration[]): void {
   for (let j = 0; j < member.childCount; j++) {
     const el = member.child(j);
-    if (!el || el.type !== 'const_element') continue;
+    if (el?.type !== 'const_element') continue;
     const nameNode = el.childForFieldName('name') || findChild(el, 'name');
     if (nameNode) {
       children.push({

package/src/extractors/python.ts

@@ -291,7 +291,7 @@ function extractClassAssignment(
   const assignment = findChild(child, 'assignment');
   if (!assignment) return;
   const left = assignment.childForFieldName('left');
-  if (!left || left.type !== 'identifier' || seen.has(left.text)) return;
+  if (left?.type !== 'identifier' || seen.has(left.text)) return;
   seen.add(left.text);
   props.push({
     name: left.text,
@@ -308,7 +308,7 @@ function extractInitProperties(
   props: SubDeclaration[],
 ): void {
   const fnName = node.childForFieldName('name');
-  if (!fnName || fnName.text !== '__init__') return;
+  if (fnName?.text !== '__init__') return;
   const initBody = node.childForFieldName('body') || findChild(node, 'block');
   if (initBody) walkInitBody(initBody, seen, props);
 }
@@ -342,11 +342,11 @@ function extractPythonClassProperties(classNode: TreeSitterNode): SubDeclaration
 function walkInitBody(bodyNode: TreeSitterNode, seen: Set<string>, props: SubDeclaration[]): void {
   for (let i = 0; i < bodyNode.childCount; i++) {
     const stmt = bodyNode.child(i);
-    if (!stmt || stmt.type !== 'expression_statement') continue;
+    if (stmt?.type !== 'expression_statement') continue;
     const assignment = findChild(stmt, 'assignment');
     if (!assignment) continue;
     const left = assignment.childForFieldName('left');
-    if (!left || left.type !== 'attribute') continue;
+    if (left?.type !== 'attribute') continue;
     const obj = left.childForFieldName('object');
     const attr = left.childForFieldName('attribute');
     if (obj && obj.text === 'self' && attr && attr.type === 'identifier' && !seen.has(attr.text)) {
@@ -370,7 +370,7 @@ function handlePyTypedParam(node: TreeSitterNode, ctx: ExtractorOutput): void {
   const isDefault = node.type === 'typed_default_parameter';
   const nameNode = isDefault ? node.childForFieldName('name') : node.child(0);
   const typeNode = node.childForFieldName('type');
-  if (!nameNode || nameNode.type !== 'identifier' || !typeNode) return;
+  if (nameNode?.type !== 'identifier' || !typeNode) return;
   if (nameNode.text === 'self' || nameNode.text === 'cls') return;
   const typeName = extractPythonTypeName(typeNode);
   if (typeName && ctx.typeMap) setTypeMapEntry(ctx.typeMap, nameNode.text, typeName, 0.9);
@@ -380,7 +380,7 @@ function handlePyTypedParam(node: TreeSitterNode, ctx: ExtractorOutput): void {
 function handlePyAssignmentType(node: TreeSitterNode, ctx: ExtractorOutput): void {
   const left = node.childForFieldName('left');
   const right = node.childForFieldName('right');
-  if (!left || left.type !== 'identifier' || !right || right.type !== 'call') return;
+  if (left?.type !== 'identifier' || !right || right.type !== 'call') return;
 
   const fn = right.childForFieldName('function');
   if (!fn) return;
@@ -391,7 +391,7 @@ function handlePyAssignmentType(node: TreeSitterNode, ctx: ExtractorOutput): voi
     }
   } else if (fn.type === 'attribute') {
     const obj = fn.childForFieldName('object');
-    if (!obj || obj.type !== 'identifier') return;
+    if (obj?.type !== 'identifier') return;
     const objName = obj.text;
     if (objName[0] && objName[0] !== objName[0].toLowerCase() && !BUILTIN_GLOBALS_PY.has(objName)) {
       if (ctx.typeMap) setTypeMapEntry(ctx.typeMap, left.text, objName, 0.7);

package/src/extractors/ruby.ts

@@ -264,7 +264,7 @@ function extractRubyBodyConstants(containerNode: TreeSitterNode): SubDeclaration
   if (!body) return children;
   for (let i = 0; i < body.childCount; i++) {
     const child = body.child(i);
-    if (!child || child.type !== 'assignment') continue;
+    if (child?.type !== 'assignment') continue;
     const left = child.childForFieldName('left');
     if (left && left.type === 'constant') {
       children.push({ name: left.text, kind: 'constant', line: child.startPosition.row + 1 });
@@ -279,7 +279,7 @@ function extractRubyClassChildren(classNode: TreeSitterNode): SubDeclaration[] {
   if (!body) return children;
   for (let i = 0; i < body.childCount; i++) {
     const child = body.child(i);
-    if (!child || child.type !== 'assignment') continue;
+    if (child?.type !== 'assignment') continue;
     const left = child.childForFieldName('left');
     if (!left) continue;
     if (left.type === 'instance_variable') {

package/src/extractors/scala.ts

@@ -263,7 +263,7 @@ function extractScalaParameters(funcNode: TreeSitterNode): SubDeclaration[] {
   if (!paramList) return params;
   for (let i = 0; i < paramList.childCount; i++) {
     const param = paramList.child(i);
-    if (!param || param.type !== 'parameter') continue;
+    if (param?.type !== 'parameter') continue;
     const nameNode = findChild(param, 'identifier');
     if (nameNode) {
       params.push({ name: nameNode.text, kind: 'parameter', line: param.startPosition.row + 1 });

package/src/extractors/solidity.ts

@@ -166,7 +166,7 @@ function extractContractMember(child: TreeSitterNode): SubDeclaration | null {
 function extractInheritance(node: TreeSitterNode, name: string, ctx: ExtractorOutput): void {
   for (let i = 0; i < node.childCount; i++) {
     const inheritance = node.child(i);
-    if (!inheritance || inheritance.type !== 'inheritance_specifier') continue;
+    if (inheritance?.type !== 'inheritance_specifier') continue;
     for (let j = 0; j < inheritance.childCount; j++) {
       const child = inheritance.child(j);
       if (!child) continue;

package/src/extractors/swift.ts

@@ -94,7 +94,7 @@ function collectSwiftEnumEntries(node: TreeSitterNode): SubDeclaration[] {
   if (!body) return entries;
   for (let i = 0; i < body.childCount; i++) {
     const child = body.child(i);
-    if (!child || child.type !== 'enum_entry') continue;
+    if (child?.type !== 'enum_entry') continue;
     const entryName = findChild(child, 'simple_identifier');
     if (entryName) {
       entries.push({
@@ -114,7 +114,7 @@ function collectSwiftProperties(node: TreeSitterNode): SubDeclaration[] {
   if (!body) return props;
   for (let i = 0; i < body.childCount; i++) {
     const child = body.child(i);
-    if (!child || child.type !== 'property_declaration') continue;
+    if (child?.type !== 'property_declaration') continue;
     const pattern = findChild(child, 'pattern');
     if (!pattern) continue;
     const propName = findChild(pattern, 'simple_identifier');
@@ -136,7 +136,7 @@ function collectSwiftMethods(node: TreeSitterNode, className: string, ctx: Extra
   if (!body) return;
   for (let i = 0; i < body.childCount; i++) {
     const child = body.child(i);
-    if (!child || child.type !== 'function_declaration') continue;
+    if (child?.type !== 'function_declaration') continue;
     const methName = findChild(child, 'simple_identifier');
     if (methName) {
       ctx.definitions.push({
@@ -159,7 +159,7 @@ function collectSwiftInheritance(
   let first = true;
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
-    if (!child || child.type !== 'inheritance_specifier') continue;
+    if (child?.type !== 'inheritance_specifier') continue;
     const userType = findChild(child, 'user_type');
     const typeId = userType ? findChild(userType, 'type_identifier') : null;
     if (!typeId) continue;

package/src/extractors/zig.ts

@@ -86,7 +86,7 @@ function extractZigParams(funcNode: TreeSitterNode): SubDeclaration[] {
 
   for (let i = 0; i < paramList.childCount; i++) {
     const param = paramList.child(i);
-    if (!param || param.type !== 'parameter') continue;
+    if (param?.type !== 'parameter') continue;
     const nameNode = findChild(param, 'identifier');
     if (nameNode) {
       params.push({ name: nameNode.text, kind: 'parameter', line: param.startPosition.row + 1 });
@@ -151,7 +151,7 @@ function zigContainerKind(nodeType: string): 'struct' | 'enum' | undefined {
 function tryHandleZigImportDecl(node: TreeSitterNode, name: string, ctx: ExtractorOutput): boolean {
   for (let i = 0; i < node.childCount; i++) {
     const child = node.child(i);
-    if (!child || child.type !== 'builtin_function') continue;
+    if (child?.type !== 'builtin_function') continue;
     const source = extractZigImportSource(child);
     if (source) {
       ctx.imports.push({ source, names: [name], line: node.startPosition.row + 1 });
@@ -175,7 +175,7 @@ function extractZigContainerFields(container: TreeSitterNode): SubDeclaration[]
   const fields: SubDeclaration[] = [];
   for (let i = 0; i < container.childCount; i++) {
     const child = container.child(i);
-    if (!child || child.type !== 'container_field') continue;
+    if (child?.type !== 'container_field') continue;
     const nameNode = child.childForFieldName('name') || findChild(child, 'identifier');
     if (nameNode) {
       fields.push({ name: nameNode.text, kind: 'property', line: child.startPosition.row + 1 });
@@ -191,7 +191,7 @@ function extractZigContainerMethods(
 ): void {
   for (let i = 0; i < container.childCount; i++) {
     const child = container.child(i);
-    if (!child || child.type !== 'function_declaration') continue;
+    if (child?.type !== 'function_declaration') continue;
     const nameNode = child.childForFieldName('name');
     if (nameNode) {
       ctx.definitions.push({

package/src/features/structure.ts

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { getNodeId, testFilterSQL } from '../db/index.js';
+import { getBuildMeta, getNodeId, setBuildMeta, testFilterSQL } from '../db/index.js';
 import { debug } from '../infrastructure/logger.js';
 import { normalizePath } from '../shared/constants.js';
 import type { BetterSqlite3Database } from '../types.js';
@@ -582,6 +582,111 @@ function buildClassifierInput(
   }));
 }
 
+// ─── Median cache helpers ─────────────────────────────────────────────────────
+
+const ROLES_MEDIANS_KEY = 'roles_medians';
+
+// Invalidate cached medians when the edge count drifts past this threshold.
+// A 1-file rebuild adds/removes < 100 edges — well within the margin.
+const MEDIAN_INVALIDATION_DELTA = 500;
+
+/**
+ * Full edge-table GROUP BY scan — O(M). Only runs on cache miss.
+ *
+ * Joins `nodes` to restrict to the same non-leaf kinds that
+ * `classifyNodeRolesFull` uses when computing medians from in-memory rows
+ * (excludes 'file', 'directory', 'parameter', 'property'). This keeps the
+ * two paths consistent so a cold-cache fallback produces the same distribution
+ * as the full-build cached value.
+ *
+ * Also returns the filtered edge count used for computing the medians so the
+ * caller can pass it directly to `writeMedianCache` without a second query.
+ */
+function computeGlobalMediansFromEdges(db: BetterSqlite3Database): {
+  fanIn: number;
+  fanOut: number;
+  edgeCount: number;
+} {
+  const excludedKinds = `('file', 'directory', 'parameter', 'property')`;
+  const fanInRows = db
+    .prepare(
+      `SELECT COUNT(*) AS cnt FROM edges e
+       JOIN nodes t ON e.target_id = t.id
+       WHERE e.kind IN ('calls', 'imports-type')
+         AND t.kind NOT IN ${excludedKinds}
+       GROUP BY e.target_id`,
+    )
+    .all() as { cnt: number }[];
+  const fanOutRows = db
+    .prepare(
+      `SELECT COUNT(*) AS cnt FROM edges e
+       JOIN nodes s ON e.source_id = s.id
+       WHERE e.kind = 'calls'
+         AND s.kind NOT IN ${excludedKinds}
+       GROUP BY e.source_id`,
+    )
+    .all() as { cnt: number }[];
+  const fanInDist = fanInRows.map((r) => r.cnt).sort((a, b) => a - b);
+  const fanOutDist = fanOutRows.map((r) => r.cnt).sort((a, b) => a - b);
+  // Sum of fanInRows[*].cnt equals the total edge count for the relevant
+  // edge subset — no extra COUNT query needed.
+  const edgeCount = fanInRows.reduce((acc, r) => acc + r.cnt, 0);
+  return { fanIn: median(fanInDist), fanOut: median(fanOutDist), edgeCount };
+}
+
+/**
+ * Read cached role medians from build_meta. Returns null when absent or stale
+ * (edge count moved beyond MEDIAN_INVALIDATION_DELTA from the cached value).
+ *
+ * The staleness check uses the same edge subset (calls + imports-type) that
+ * the medians are derived from, so only changes to the edges that actually
+ * influence fan-in/fan-out can evict the cache.
+ */
+function readCachedMedians(db: BetterSqlite3Database): { fanIn: number; fanOut: number } | null {
+  const raw = getBuildMeta(db, ROLES_MEDIANS_KEY);
+  if (!raw) return null;
+  try {
+    const cached = JSON.parse(raw) as { fanIn: number; fanOut: number; edgeCount: number };
+    // Count only the edge kinds that drive median computation — same subset
+    // used by computeGlobalMediansFromEdges and classifyNodeRolesFull.
+    const currentCount = (
+      db
+        .prepare(`SELECT COUNT(*) AS cnt FROM edges WHERE kind IN ('calls', 'imports-type')`)
+        .get() as { cnt: number }
+    ).cnt;
+    if (
+      Math.abs(currentCount - cached.edgeCount) >
+      Math.max(MEDIAN_INVALIDATION_DELTA, cached.edgeCount * 0.1)
+    )
+      return null;
+    return { fanIn: cached.fanIn, fanOut: cached.fanOut };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Persist global role medians + current edge count to build_meta.
+ *
+ * @param edgeCount - pre-computed calls+imports-type edge count. When provided,
+ *   the function skips the COUNT query entirely. Pass when the count is already
+ *   known at the call site (e.g. from `computeGlobalMediansFromEdges`).
+ */
+function writeMedianCache(
+  db: BetterSqlite3Database,
+  medians: { fanIn: number; fanOut: number },
+  edgeCount?: number,
+): void {
+  const cnt =
+    edgeCount ??
+    (
+      db
+        .prepare(`SELECT COUNT(*) AS cnt FROM edges WHERE kind IN ('calls', 'imports-type')`)
+        .get() as { cnt: number }
+    ).cnt;
+  setBuildMeta(db, { [ROLES_MEDIANS_KEY]: JSON.stringify({ ...medians, edgeCount: cnt }) });
+}
+
 function classifyNodeRolesFull(db: BetterSqlite3Database, emptySummary: RoleSummary): RoleSummary {
   // Leaf kinds (parameter, property) can never have callers/callees.
   // Classify them directly as dead-leaf without the expensive fan-in/fan-out JOINs.
@@ -672,10 +777,28 @@ function classifyNodeRolesFull(db: BetterSqlite3Database, emptySummary: RoleSumm
     prodFanInMap.set(r.target_id, r.cnt);
   }
 
-  // Delegate classification to the pure-logic classifier
+  // Delegate classification to the pure-logic classifier.
+  // Compute medians from the already-loaded rows (no extra DB round-trip),
+  // pass them as overrides to avoid recomputing inside classifyRoles,
+  // and cache them for subsequent incremental builds.
   const activeFiles = buildActiveFilesSet(rows);
   const classifierInput = buildClassifierInput(rows, exportedIds, prodFanInMap, activeFiles);
-  const roleMap = classifyRoles(classifierInput);
+  const nonZeroFanIn = classifierInput
+    .filter((n) => n.fanIn > 0)
+    .map((n) => n.fanIn)
+    .sort((a, b) => a - b);
+  const nonZeroFanOut = classifierInput
+    .filter((n) => n.fanOut > 0)
+    .map((n) => n.fanOut)
+    .sort((a, b) => a - b);
+  const globalMedians = { fanIn: median(nonZeroFanIn), fanOut: median(nonZeroFanOut) };
+  const roleMap = classifyRoles(classifierInput, globalMedians);
+  // Derive the edge count from already-loaded in-memory rows: summing fan_in
+  // across all nodes equals COUNT(*) FROM edges WHERE kind IN ('calls','imports-type'),
+  // since the full-build query left-joins every matching edge exactly once per target.
+  // Passing this avoids an extra COUNT query on the full-build path.
+  const inMemoryEdgeCount = rows.reduce((acc, r) => acc + r.fan_in, 0);
+  writeMedianCache(db, globalMedians, inMemoryEdgeCount);
 
   const { summary, idsByRole } = buildRoleSummary(rows, leafRows, roleMap, emptySummary);
 
@@ -691,7 +814,9 @@ function classifyNodeRolesFull(db: BetterSqlite3Database, emptySummary: RoleSumm
  * plus their immediate edge neighbours (callers and callees in other files).
  *
  * Uses indexed point lookups for fan-in/fan-out instead of full table scans.
- * Global medians are computed from edge distribution (fast GROUP BY on index).
+ * Global medians are read from the build_meta cache written by the last full
+ * classification; the cache is only recomputed when the edge count drifts
+ * beyond MEDIAN_INVALIDATION_DELTA (i.e. large structural changes).
  * Unchanged files not connected to changed files keep their roles from the
  * previous build.
  */
@@ -718,25 +843,20 @@ function classifyNodeRolesIncremental(
   const allAffectedFiles = [...changedFiles, ...neighbourFiles.map((r) => r.file)];
   const placeholders = allAffectedFiles.map(() => '?').join(',');
 
-  // 1. Compute global medians from edge distribution (fast: scans edge index, no node join)
-  const fanInDist = (
-    db
-      .prepare(
-        `SELECT COUNT(*) AS cnt FROM edges WHERE kind IN ('calls', 'imports-type') GROUP BY target_id`,
-      )
-      .all() as { cnt: number }[]
-  )
-    .map((r) => r.cnt)
-    .sort((a, b) => a - b);
-  const fanOutDist = (
-    db
-      .prepare(`SELECT COUNT(*) AS cnt FROM edges WHERE kind = 'calls' GROUP BY source_id`)
-      .all() as { cnt: number }[]
-  )
-    .map((r) => r.cnt)
-    .sort((a, b) => a - b);
-
-  const globalMedians = { fanIn: median(fanInDist), fanOut: median(fanOutDist) };
+  // 1. Read global medians from cache; fall back to full edge scan only on miss.
+  // The median barely moves for a 1-file change, so the cache is almost always
+  // valid, eliminating 2× full edge-table GROUP BY queries (~10-15 ms on large graphs).
+  const cachedMedians = readCachedMedians(db);
+  let globalMedians: { fanIn: number; fanOut: number };
+  if (cachedMedians) {
+    globalMedians = cachedMedians;
+  } else {
+    const computed = computeGlobalMediansFromEdges(db);
+    // Pass the edgeCount returned by computeGlobalMediansFromEdges so
+    // writeMedianCache does not issue a second COUNT query.
+    writeMedianCache(db, computed, computed.edgeCount);
+    globalMedians = computed;
+  }
 
   // 2a. Leaf kinds (parameter, property) in affected files — always dead-leaf
   const leafRows = db

package/src/infrastructure/config.ts

@@ -24,6 +24,7 @@ export const DEFAULTS = {
     dbPath: '.codegraph/graph.db',
     driftThreshold: 0.2,
     smallFilesThreshold: 5,
+    typescriptResolver: false,
   },
   query: {
     defaultDepth: 3,
@@ -79,6 +80,20 @@ export const DEFAULTS = {
     briefImporterDepth: 5,
     briefHighRiskCallers: 10,
     briefMediumRiskCallers: 3,
+    // TODO(Phase 8.3): wire these into the points-to solver and type-propagation path
+    // once config is threaded through to extractSymbols / buildPointsToMap. Currently
+    // controlled by hardcoded constants in src/extractors/javascript.ts
+    // (MAX_PROPAGATION_DEPTH, PROPAGATION_HOP_PENALTY) and in
+    // src/domain/graph/resolver/points-to.ts (MAX_SOLVER_ITERATIONS).
+    typePropagationDepth: 3,
+    /**
+     * Maximum fixed-point iterations for the Phase 8.3 points-to solver.
+     * @reserved — currently not wired to either the WASM solver
+     * (`MAX_SOLVER_ITERATIONS` in `points-to.ts`) or the native Rust solver
+     * (`MAX_SOLVER_ITERATIONS` in `edge_builder.rs`), both of which use the
+     * same hardcoded value of 50.  See the TODO comment above.
+     */
+    pointsToMaxIterations: 50,
   },
   community: {
     resolution: 1.0,

package/src/infrastructure/native.ts

@@ -6,11 +6,13 @@
  * to the existing WASM pipeline.
  */
 
+import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import os from 'node:os';
+import { fileURLToPath } from 'node:url';
 import { EngineError, toErrorMessage } from '../shared/errors.js';
 import type { NativeAddon } from '../types.js';
-import { debug } from './logger.js';
+import { debug, warn } from './logger.js';
 
 let _cached: NativeAddon | null | undefined; // undefined = not yet tried, null = failed, NativeAddon = module
 let _loadError: Error | null = null;
@@ -44,31 +46,107 @@ const PLATFORM_PACKAGES: Record<string, string> = {
   'win32-x64': '@optave/codegraph-win32-x64-msvc',
 };
 
+/**
+ * Map of (platform-arch[-libc]) → locally compiled binary filename.
+ * Checked before the npm package so that locally compiled Rust changes
+ * are picked up immediately in development without publishing a new release.
+ */
+const PLATFORM_LOCAL_BINARIES: Record<string, string> = {
+  'linux-x64-gnu': 'codegraph-core.linux-x64-gnu.node',
+  'linux-x64-musl': 'codegraph-core.linux-x64-musl.node',
+  'linux-arm64-gnu': 'codegraph-core.linux-arm64-gnu.node',
+  'linux-arm64-musl': 'codegraph-core.linux-arm64-musl.node',
+  'darwin-arm64': 'codegraph-core.darwin-arm64.node',
+  'darwin-x64': 'codegraph-core.darwin-x64.node',
+  'win32-x64': 'codegraph-core.win32-x64-msvc.node',
+};
+
+/** Compute the platform key used to index PLATFORM_PACKAGES / PLATFORM_LOCAL_BINARIES. */
+function resolvePlatformKey(): string {
+  const platform = os.platform();
+  const arch = os.arch();
+  return platform === 'linux' ? `${platform}-${arch}-${detectLibc()}` : `${platform}-${arch}`;
+}
+
 /**
  * Resolve the platform-specific npm package name for the native addon.
  * Returns null if the current platform is not supported.
  */
 function resolvePlatformPackage(): string | null {
-  const platform = os.platform();
-  const arch = os.arch();
-  const key = platform === 'linux' ? `${platform}-${arch}-${detectLibc()}` : `${platform}-${arch}`;
-  return PLATFORM_PACKAGES[key] || null;
+  return PLATFORM_PACKAGES[resolvePlatformKey()] ?? null;
 }
 
 /**
  * Try to load the native napi addon.
  * Returns the module on success, null on failure.
+ *
+ * Load order:
+ *   1. NAPI_RS_NATIVE_LIBRARY_PATH env var (explicit override)
+ *   2. locally compiled binary in crates/codegraph-core/ (dev mode — preferred
+ *      over the npm package so that Rust changes are picked up immediately
+ *      without publishing a new release)
+ *   3. npm platform package (production path)
  */
 export function loadNative(): NativeAddon | null {
   if (_cached !== undefined) return _cached;
 
+  const platformKey = resolvePlatformKey();
+
+  // 1. Explicit path override — highest priority. Failure is fatal: if the
+  //    operator set this variable, silently loading a different binary would
+  //    be harder to diagnose than an explicit error.
+  const envPath = process.env.NAPI_RS_NATIVE_LIBRARY_PATH;
+  if (envPath) {
+    try {
+      _cached = _require(envPath) as NativeAddon;
+      debug(`loadNative: loaded from NAPI_RS_NATIVE_LIBRARY_PATH: ${envPath}`);
+      return _cached;
+    } catch (err) {
+      _loadError = err as Error;
+      warn(
+        `loadNative: NAPI_RS_NATIVE_LIBRARY_PATH is set but failed to load "${envPath}": ${toErrorMessage(err as Error)}`,
+      );
+      _cached = null;
+      return null;
+    }
+  }
+
+  // 2. Locally compiled dev binary — preferred over npm package so that Rust
+  //    changes are visible without publishing. Only used when the file exists.
+  //    If the file exists but fails to load (e.g. stale ABI), we warn and halt
+  //    rather than silently falling through to the npm package — that would
+  //    defeat the purpose of this priority order.
+  const localFile = PLATFORM_LOCAL_BINARIES[platformKey];
+  if (localFile) {
+    const localPath = fileURLToPath(
+      new URL(`../../crates/codegraph-core/${localFile}`, import.meta.url),
+    );
+    if (existsSync(localPath)) {
+      try {
+        _cached = _require(localPath) as NativeAddon;
+        debug(`loadNative: loaded local dev binary: ${localPath}`);
+        return _cached;
+      } catch (err) {
+        _loadError = err as Error;
+        warn(
+          `loadNative: local dev binary exists but failed to load "${localPath}": ${toErrorMessage(err as Error)}`,
+        );
+        _cached = null;
+        return null;
+      }
+    }
+  }
+
+  // 3. Published npm platform package — production path.
   const pkg = resolvePlatformPackage();
   if (pkg) {
     try {
       _cached = _require(pkg) as NativeAddon;
+      debug(`loadNative: loaded npm package: ${pkg}`);
       return _cached;
     } catch (err) {
       _loadError = err as Error;
+      debug(`loadNative: npm package ${pkg} not available: ${toErrorMessage(err as Error)}`);
     }
   } else {
     _loadError = new Error(`Unsupported platform: ${os.platform()}-${os.arch()}`);
@@ -88,6 +166,10 @@ export function isNativeAvailable(): boolean {
 /**
  * Read the version from the platform-specific npm package.json.
  * Returns null if the package is not installed or has no version.
+ *
+ * Note: always reports the npm package version. When the local dev binary or
+ * NAPI_RS_NATIVE_LIBRARY_PATH is loaded instead, this version may not match
+ * the running binary.
  */
 export function getNativePackageVersion(): string | null {
   const pkg = resolvePlatformPackage();