gitnexus 1.6.2 → 1.6.3-rc.10

package/dist/core/ingestion/model/resolve.d.ts

@@ -5,7 +5,7 @@
  * using only the SemanticModel registries and HeritageMap — NO dependency
  * on resolution-context.ts (circular dependency risk).
  */
-import type { SymbolDefinition } from './symbol-table.js';
+import type { SymbolDefinition } from '../../../_shared/index.js';
 import type { SemanticModel } from './semantic-model.js';
 import type { HeritageMap } from './heritage-map.js';
 import type { MroStrategy } from '../../../_shared/index.js';

package/dist/core/ingestion/model/symbol-table.d.ts

@@ -33,7 +33,7 @@
  * import from `./model/` here, you are going the wrong way — move the
  * logic up the dependency chain instead.
  */
-import type { NodeLabel } from '../../../_shared/index.js';
+import type { NodeLabel, SymbolDefinition } from '../../../_shared/index.js';
 /**
  * Class-like NodeLabels — used for qualifiedName fallback inside
  * `SymbolTable.add()` and (via import into `model/registration-table.ts`)
@@ -89,28 +89,6 @@ export declare const FREE_CALLABLE_TYPES: ReadonlySet<NodeLabel>;
  *  `filterCallableCandidates` / `countCallableCandidates`.
  */
 export declare const CALL_TARGET_TYPES: ReadonlySet<NodeLabel>;
-export interface SymbolDefinition {
-    nodeId: string;
-    filePath: string;
-    type: NodeLabel;
-    /** Canonical dot-separated qualified type name for class-like symbols
-     *  (e.g. `App.Models.User`). Falls back to the simple symbol name when no
-     *  package/namespace/module scope exists or no explicit qualified metadata is provided. */
-    qualifiedName?: string;
-    parameterCount?: number;
-    /** Number of required (non-optional, non-default) parameters.
-     *  Enables range-based arity filtering: argCount >= requiredParameterCount && argCount <= parameterCount. */
-    requiredParameterCount?: number;
-    /** Per-parameter type names for overload disambiguation (e.g. ['int', 'String']).
-     *  Populated when parameter types are resolvable from AST (any typed language). */
-    parameterTypes?: string[];
-    /** Raw return type text extracted from AST (e.g. 'User', 'Promise<User>') */
-    returnType?: string;
-    /** Declared type for non-callable symbols — fields/properties (e.g. 'Address', 'List<User>') */
-    declaredType?: string;
-    /** Links Method/Constructor/Property to owning Class/Struct/Trait nodeId */
-    ownerId?: string;
-}
 /**
  * Optional metadata accepted by {@link SymbolTable.add}. Kept as a separate
  * type alias so callers and wrappers can share the same shape.

package/dist/core/ingestion/model/type-registry.d.ts

@@ -5,7 +5,7 @@
  * Eagerly-populated indexes keyed by symbol name and qualified name.
  * Also includes a separate index for Rust Impl blocks.
  */
-import type { SymbolDefinition } from './symbol-table.js';
+import type { SymbolDefinition } from '../../../_shared/index.js';
 export interface TypeRegistry {
     /**
      * Look up class-like definitions (Class, Struct, Interface, Enum, Record, Trait)

package/dist/core/search/phase-timer.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Per-phase wall-clock timing for the search pipeline and similar
+ * multi-stage flows. Designed to be called from query() with minimal
+ * ceremony and negligible overhead (< 0.1 ms per phase recorded).
+ *
+ * ### Sequential usage
+ *
+ * ```ts
+ * const t = new PhaseTimer();
+ * t.start('bm25'); await bm25Search(...); t.stop();
+ * t.start('merge'); doMerge(); t.stop();
+ * const phases = t.summary(); // { bm25: 42, merge: 3 }
+ * ```
+ *
+ * ### Concurrent usage (Promise.all)
+ *
+ * `start`/`stop` assume a single active phase at a time, which is wrong
+ * for concurrent work inside `Promise.all` — the second `start` would
+ * auto-stop the first and only one of the two would get timed. Use
+ * {@link PhaseTimer.time} to wrap each concurrent promise instead:
+ *
+ * ```ts
+ * const [a, b] = await Promise.all([
+ *   t.time('bm25', bm25Search(...)),
+ *   t.time('vector', semanticSearch(...)),
+ * ]);
+ * ```
+ *
+ * ### Pre-measured durations
+ *
+ * ```ts
+ * t.mark('inherited', 12.5);
+ * ```
+ */
+export declare class PhaseTimer {
+    private phases;
+    private current;
+    private t0;
+    /** Start a new phase. Implicitly stops the previous one, if any. */
+    start(phase: string): void;
+    /** Stop the current phase. No-op if no phase is active. */
+    stop(): void;
+    /**
+     * Record a pre-measured duration without touching the active phase.
+     * Use for concurrent operations inside `Promise.all` where
+     * `start`/`stop` would step on each other, or for durations imported
+     * from sub-systems. Additive across repeated calls with the same
+     * phase name. Ignores negative / non-finite inputs.
+     */
+    mark(phase: string, durationMs: number): void;
+    /**
+     * Wrap a promise with automatic timing. Records wall time via
+     * {@link PhaseTimer.mark} regardless of which other phases are
+     * active — safe to use inside `Promise.all`.
+     */
+    time<T>(phase: string, promise: Promise<T>): Promise<T>;
+    /**
+     * Snapshot of accumulated durations rounded to 0.1 ms. Stops the
+     * current phase if one is still running.
+     */
+    summary(): Record<string, number>;
+    /**
+     * Sum of every recorded phase duration.
+     *
+     * Note: for phases recorded via {@link PhaseTimer.time} or
+     * {@link PhaseTimer.mark} this is the *sum*, not the wall time —
+     * concurrent work overlaps and the sum can exceed the end-to-end
+     * wall time. Record wall time separately with `mark('wall', …)` if
+     * that distinction matters.
+     */
+    totalMs(): number;
+}

package/dist/core/search/phase-timer.js

@@ -0,0 +1,106 @@
+/**
+ * Per-phase wall-clock timing for the search pipeline and similar
+ * multi-stage flows. Designed to be called from query() with minimal
+ * ceremony and negligible overhead (< 0.1 ms per phase recorded).
+ *
+ * ### Sequential usage
+ *
+ * ```ts
+ * const t = new PhaseTimer();
+ * t.start('bm25'); await bm25Search(...); t.stop();
+ * t.start('merge'); doMerge(); t.stop();
+ * const phases = t.summary(); // { bm25: 42, merge: 3 }
+ * ```
+ *
+ * ### Concurrent usage (Promise.all)
+ *
+ * `start`/`stop` assume a single active phase at a time, which is wrong
+ * for concurrent work inside `Promise.all` — the second `start` would
+ * auto-stop the first and only one of the two would get timed. Use
+ * {@link PhaseTimer.time} to wrap each concurrent promise instead:
+ *
+ * ```ts
+ * const [a, b] = await Promise.all([
+ *   t.time('bm25', bm25Search(...)),
+ *   t.time('vector', semanticSearch(...)),
+ * ]);
+ * ```
+ *
+ * ### Pre-measured durations
+ *
+ * ```ts
+ * t.mark('inherited', 12.5);
+ * ```
+ */
+export class PhaseTimer {
+    phases = new Map();
+    current = null;
+    t0 = 0;
+    /** Start a new phase. Implicitly stops the previous one, if any. */
+    start(phase) {
+        this.stop();
+        this.current = phase;
+        this.t0 = performance.now();
+    }
+    /** Stop the current phase. No-op if no phase is active. */
+    stop() {
+        if (this.current !== null) {
+            const elapsed = performance.now() - this.t0;
+            this.phases.set(this.current, (this.phases.get(this.current) ?? 0) + elapsed);
+            this.current = null;
+        }
+    }
+    /**
+     * Record a pre-measured duration without touching the active phase.
+     * Use for concurrent operations inside `Promise.all` where
+     * `start`/`stop` would step on each other, or for durations imported
+     * from sub-systems. Additive across repeated calls with the same
+     * phase name. Ignores negative / non-finite inputs.
+     */
+    mark(phase, durationMs) {
+        if (!Number.isFinite(durationMs) || durationMs < 0)
+            return;
+        this.phases.set(phase, (this.phases.get(phase) ?? 0) + durationMs);
+    }
+    /**
+     * Wrap a promise with automatic timing. Records wall time via
+     * {@link PhaseTimer.mark} regardless of which other phases are
+     * active — safe to use inside `Promise.all`.
+     */
+    async time(phase, promise) {
+        const t0 = performance.now();
+        try {
+            return await promise;
+        }
+        finally {
+            this.mark(phase, performance.now() - t0);
+        }
+    }
+    /**
+     * Snapshot of accumulated durations rounded to 0.1 ms. Stops the
+     * current phase if one is still running.
+     */
+    summary() {
+        this.stop();
+        const out = {};
+        for (const [k, v] of this.phases)
+            out[k] = Math.round(v * 10) / 10;
+        return out;
+    }
+    /**
+     * Sum of every recorded phase duration.
+     *
+     * Note: for phases recorded via {@link PhaseTimer.time} or
+     * {@link PhaseTimer.mark} this is the *sum*, not the wall time —
+     * concurrent work overlaps and the sum can exceed the end-to-end
+     * wall time. Record wall time separately with `mark('wall', …)` if
+     * that distinction matters.
+     */
+    totalMs() {
+        this.stop();
+        let t = 0;
+        for (const v of this.phases.values())
+            t += v;
+        return Math.round(t * 10) / 10;
+    }
+}

package/dist/mcp/local/local-backend.d.ts

@@ -150,9 +150,56 @@ export declare class LocalBackend {
      */
     private aggregateClusters;
     private overview;
+    /**
+     * Patch the `type` field on candidates whose `labels(n)[0]` projection
+     * came back empty — a known LadybugDB behaviour for several node types.
+     *
+     * Uses one scoped UNION query across the five priority labels rather
+     * than per-candidate round-trips, so cost is a single DB call regardless
+     * of how many candidates need enrichment. No-op when every candidate
+     * already has a non-empty type.
+     *
+     * Failures are swallowed: label enrichment is an optimisation for
+     * downstream scoring and #480 Class/Interface BFS seeding; if it fails
+     * the symbol still resolves, just without the kind-priority bonus.
+     */
+    private enrichCandidateLabels;
+    /**
+     * Score a symbol candidate for disambiguation ranking.
+     *
+     * Deterministic, no DB round-trip:
+     *   - base 0.50
+     *   - +0.40 when file_path hint matches (substring, case-insensitive)
+     *   - +0.20 when kind hint exactly matches the candidate's kind
+     *   - when no kind hint, a small priority bonus (Class > Interface >
+     *     Function > Method > Constructor) to preserve the intuition that
+     *     class-level names are usually what the user wanted.
+     *
+     * Capped at 1.0. Intentionally simple and inspectable — a future v2 can
+     * plug in BM25/embedding signals here without changing the surrounding
+     * resolver shape.
+     */
+    private scoreCandidate;
+    /**
+     * Shared symbol resolver used by `context` and `impact`.
+     *
+     * Returns one of:
+     *   - `{ kind: 'ok', symbol, resolvedLabel }` — single confident match
+     *     (either direct UID, only one candidate after filtering, Class/
+     *     Constructor collapse, or a top-scoring candidate with a clear gap
+     *     to the runner-up).
+     *   - `{ kind: 'ambiguous', candidates }` — multiple viable matches,
+     *     sorted by score desc. Each candidate carries a relevance score.
+     *   - `{ kind: 'not_found' }` — no matches at all.
+     *
+     * Preserves the #480 Class/Constructor preference: when the only
+     * ambiguity is between a Class and its own Constructor (same name,
+     * same filePath), the Class wins silently.
+     */
+    private resolveSymbolCandidates;
     /**
      * Context tool — 360-degree symbol view with categorized refs.
-     * Disambiguation when multiple symbols share a name.
+     * Disambiguation (ranked) when multiple symbols share a name.
      * UID-based direct lookup. No cluster in output.
      */
     private context;