gitnexus 1.6.0 → 1.6.2-rc.1

package/dist/core/ingestion/pipeline-phases/scan.js

@@ -0,0 +1,46 @@
+/**
+ * Phase: scan
+ *
+ * Walks the repository filesystem and collects file paths + sizes.
+ * Does NOT read file contents — that happens in downstream phases.
+ *
+ * @deps    (none — this is the pipeline root)
+ * @reads   repoPath (filesystem)
+ * @writes  graph (nothing yet — just returns scanned paths)
+ * @output  ScannedFile[], allPaths[], totalFiles
+ */
+import { walkRepositoryPaths } from '../filesystem-walker.js';
+export const scanPhase = {
+    name: 'scan',
+    deps: [],
+    async execute(ctx) {
+        ctx.onProgress({
+            phase: 'extracting',
+            percent: 0,
+            message: 'Scanning repository...',
+        });
+        const scannedFiles = await walkRepositoryPaths(ctx.repoPath, (current, total, filePath) => {
+            const scanProgress = Math.round((current / total) * 15);
+            ctx.onProgress({
+                phase: 'extracting',
+                percent: scanProgress,
+                message: 'Scanning repository...',
+                detail: filePath,
+                stats: {
+                    filesProcessed: current,
+                    totalFiles: total,
+                    nodesCreated: ctx.graph.nodeCount,
+                },
+            });
+        });
+        const totalFiles = scannedFiles.length;
+        const allPaths = scannedFiles.map((f) => f.path);
+        ctx.onProgress({
+            phase: 'extracting',
+            percent: 15,
+            message: 'Repository scanned successfully',
+            stats: { filesProcessed: totalFiles, totalFiles, nodesCreated: ctx.graph.nodeCount },
+        });
+        return { scannedFiles, allPaths, totalFiles };
+    },
+};

package/dist/core/ingestion/pipeline-phases/structure.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Phase: structure
+ *
+ * Builds File and Folder nodes in the graph from scanned paths.
+ *
+ * @deps    scan
+ * @reads   allPaths (from scan phase)
+ * @writes  graph (File, Folder nodes + CONTAINS edges)
+ */
+import type { PipelinePhase } from './types.js';
+/** Structure phase produces no additional data — it writes directly to the graph. */
+export interface StructureOutput {
+    /** Pass-through from scan for downstream phases. */
+    scannedFiles: {
+        path: string;
+        size: number;
+    }[];
+    allPaths: string[];
+    /**
+     * Materialized once here and shared across all downstream consumers
+     * (cobol, markdown, cross-file propagation). Avoids the previous
+     * per-phase `new Set(allPaths)` allocations on multi-thousand-file repos.
+     */
+    allPathSet: ReadonlySet<string>;
+    totalFiles: number;
+}
+export declare const structurePhase: PipelinePhase<StructureOutput>;

package/dist/core/ingestion/pipeline-phases/structure.js

@@ -0,0 +1,35 @@
+/**
+ * Phase: structure
+ *
+ * Builds File and Folder nodes in the graph from scanned paths.
+ *
+ * @deps    scan
+ * @reads   allPaths (from scan phase)
+ * @writes  graph (File, Folder nodes + CONTAINS edges)
+ */
+import { getPhaseOutput } from './types.js';
+import { processStructure } from '../structure-processor.js';
+export const structurePhase = {
+    name: 'structure',
+    deps: ['scan'],
+    async execute(ctx, deps) {
+        const { scannedFiles, allPaths, totalFiles } = getPhaseOutput(deps, 'scan');
+        ctx.onProgress({
+            phase: 'structure',
+            percent: 15,
+            message: 'Analyzing project structure...',
+            stats: { filesProcessed: 0, totalFiles, nodesCreated: ctx.graph.nodeCount },
+        });
+        processStructure(ctx.graph, allPaths);
+        ctx.onProgress({
+            phase: 'structure',
+            percent: 20,
+            message: 'Project structure analyzed',
+            stats: { filesProcessed: totalFiles, totalFiles, nodesCreated: ctx.graph.nodeCount },
+        });
+        // Build the set once here so cobol, markdown, and cross-file propagation
+        // can all reuse it instead of re-materializing `new Set(allPaths)` each.
+        const allPathSet = new Set(allPaths);
+        return { scannedFiles, allPaths, allPathSet, totalFiles };
+    },
+};

package/dist/core/ingestion/pipeline-phases/tools.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Phase: tools
+ *
+ * Detects MCP/RPC tool definitions and creates Tool graph nodes.
+ *
+ * @deps    parse
+ * @reads   allToolDefs (from parse), allPaths
+ * @writes  graph (Tool nodes, HANDLES_TOOL edges)
+ * @output  toolDefs array
+ */
+import type { PipelinePhase } from './types.js';
+export interface ToolDef {
+    name: string;
+    filePath: string;
+    description: string;
+}
+export interface ToolsOutput {
+    toolDefs: ToolDef[];
+}
+export declare const toolsPhase: PipelinePhase<ToolsOutput>;

package/dist/core/ingestion/pipeline-phases/tools.js

@@ -0,0 +1,79 @@
+/**
+ * Phase: tools
+ *
+ * Detects MCP/RPC tool definitions and creates Tool graph nodes.
+ *
+ * @deps    parse
+ * @reads   allToolDefs (from parse), allPaths
+ * @writes  graph (Tool nodes, HANDLES_TOOL edges)
+ * @output  toolDefs array
+ */
+import { getPhaseOutput } from './types.js';
+import { generateId } from '../../../lib/utils.js';
+import { readFileContents } from '../filesystem-walker.js';
+import { isDev } from '../utils/env.js';
+export const toolsPhase = {
+    name: 'tools',
+    deps: ['parse'],
+    async execute(ctx, deps) {
+        const { allToolDefs, allPaths } = getPhaseOutput(deps, 'parse');
+        const toolDefs = [];
+        const seenToolNames = new Set();
+        for (const td of allToolDefs) {
+            if (seenToolNames.has(td.toolName))
+                continue;
+            seenToolNames.add(td.toolName);
+            toolDefs.push({ name: td.toolName, filePath: td.filePath, description: td.description });
+        }
+        // TS tool definition arrays — require inputSchema nearby
+        const toolCandidatePaths = allPaths.filter((p) => (p.endsWith('.ts') || p.endsWith('.js')) &&
+            p.toLowerCase().includes('tool') &&
+            !p.includes('node_modules') &&
+            !p.includes('test') &&
+            !p.includes('__'));
+        if (toolCandidatePaths.length > 0) {
+            const toolContents = await readFileContents(ctx.repoPath, toolCandidatePaths);
+            for (const [filePath, content] of toolContents) {
+                if (!content.includes('inputSchema'))
+                    continue;
+                const toolPattern = /name:\s*['"](\w+)['"]\s*,\s*\n?\s*description:\s*[`'"]([\s\S]*?)[`'"]/g;
+                let match;
+                while ((match = toolPattern.exec(content)) !== null) {
+                    const name = match[1];
+                    if (seenToolNames.has(name))
+                        continue;
+                    seenToolNames.add(name);
+                    toolDefs.push({
+                        name,
+                        filePath,
+                        description: match[2].slice(0, 200).replace(/\n/g, ' ').trim(),
+                    });
+                }
+            }
+        }
+        // Create Tool nodes and HANDLES_TOOL edges
+        if (toolDefs.length > 0) {
+            for (const td of toolDefs) {
+                const toolNodeId = generateId('Tool', td.name);
+                ctx.graph.addNode({
+                    id: toolNodeId,
+                    label: 'Tool',
+                    properties: { name: td.name, filePath: td.filePath, description: td.description },
+                });
+                const handlerFileId = generateId('File', td.filePath);
+                ctx.graph.addRelationship({
+                    id: generateId('HANDLES_TOOL', `${handlerFileId}->${toolNodeId}`),
+                    sourceId: handlerFileId,
+                    targetId: toolNodeId,
+                    type: 'HANDLES_TOOL',
+                    confidence: 1.0,
+                    reason: 'tool-definition',
+                });
+            }
+            if (isDev) {
+                console.log(`🔧 Tool registry: ${toolDefs.length} tools detected`);
+            }
+        }
+        return { toolDefs };
+    },
+};

package/dist/core/ingestion/pipeline-phases/types.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Pipeline Phase — Type definitions.
+ *
+ * Each phase is a named node in the dependency graph with typed inputs and outputs.
+ * The runner resolves dependencies via topological sort and passes
+ * typed results from upstream phases as inputs to downstream phases.
+ *
+ * Design goals:
+ *  - Explicit data flow between phases via typed outputs
+ *  - The knowledge graph is a shared mutable accumulator — phases add nodes/edges
+ *    and may read prior phases' contributions. This is intentional: the graph is
+ *    the pipeline's primary output, not an inter-phase communication channel.
+ *  - Compile-time exhaustiveness (adding a phase = type error until wired)
+ *  - Each phase is independently testable with mocked inputs
+ */
+import type { KnowledgeGraph } from '../../graph/types.js';
+import type { PipelineProgress } from '../../../_shared/index.js';
+import type { PipelineOptions } from '../pipeline.js';
+/** Immutable context available to every phase. */
+export interface PipelineContext {
+    /** Absolute path to the repository root. */
+    readonly repoPath: string;
+    /** Mutable knowledge graph — the single shared accumulator. */
+    readonly graph: KnowledgeGraph;
+    /** Progress callback for UI updates. */
+    readonly onProgress: (progress: PipelineProgress) => void;
+    /** Pipeline options (skipGraphPhases, skipWorkers, etc.). */
+    readonly options?: PipelineOptions;
+    /** Pipeline start timestamp (for elapsed-time logging). */
+    readonly pipelineStart: number;
+}
+/** Wraps a phase's output with timing metadata. */
+export interface PhaseResult<T> {
+    /** Phase name (matches the phase's `name` field). */
+    readonly phaseName: string;
+    /** The typed output of the phase. */
+    readonly output: T;
+    /** Wall-clock duration in milliseconds. */
+    readonly durationMs: number;
+}
+/**
+ * A single phase in the ingestion pipeline.
+ *
+ * @typeParam TDeps - Tuple of dependency phase output types
+ * @typeParam TOutput - This phase's output type
+ */
+export interface PipelinePhase<TOutput = unknown> {
+    /** Unique name for logging and result lookup. */
+    readonly name: string;
+    /**
+     * Names of phases this phase depends on.
+     * The runner guarantees these have completed before execute() is called.
+     */
+    readonly deps: readonly string[];
+    /**
+     * Execute the phase.
+     *
+     * @param ctx    Shared pipeline context (graph, repoPath, progress, options)
+     * @param deps   Map of dependency name → PhaseResult (typed outputs from upstream phases)
+     * @returns      The phase's typed output
+     */
+    execute(ctx: PipelineContext, deps: ReadonlyMap<string, PhaseResult<unknown>>): Promise<TOutput>;
+}
+/**
+ * Helper to extract the typed output of a dependency phase.
+ *
+ * Type safety note: This uses an `as T` cast because the runner stores
+ * heterogeneous phase outputs in a single `Map<string, PhaseResult<unknown>>`.
+ * The cast is safe as long as callers use the correct output type for the
+ * named phase. Mismatches will surface as runtime type errors, not compile-time
+ * errors — this is an intentional trade-off for a static phase graph without
+ * a dynamic type registry.
+ *
+ * @param deps       The resolved dependency map from the runner
+ * @param phaseName  The name of the upstream phase whose output you need
+ * @returns          The typed output of the phase
+ * @throws           If the phase is not found in the dependency map
+ */
+export declare function getPhaseOutput<T>(deps: ReadonlyMap<string, PhaseResult<unknown>>, phaseName: string): T;

package/dist/core/ingestion/pipeline-phases/types.js

@@ -0,0 +1,37 @@
+/**
+ * Pipeline Phase — Type definitions.
+ *
+ * Each phase is a named node in the dependency graph with typed inputs and outputs.
+ * The runner resolves dependencies via topological sort and passes
+ * typed results from upstream phases as inputs to downstream phases.
+ *
+ * Design goals:
+ *  - Explicit data flow between phases via typed outputs
+ *  - The knowledge graph is a shared mutable accumulator — phases add nodes/edges
+ *    and may read prior phases' contributions. This is intentional: the graph is
+ *    the pipeline's primary output, not an inter-phase communication channel.
+ *  - Compile-time exhaustiveness (adding a phase = type error until wired)
+ *  - Each phase is independently testable with mocked inputs
+ */
+/**
+ * Helper to extract the typed output of a dependency phase.
+ *
+ * Type safety note: This uses an `as T` cast because the runner stores
+ * heterogeneous phase outputs in a single `Map<string, PhaseResult<unknown>>`.
+ * The cast is safe as long as callers use the correct output type for the
+ * named phase. Mismatches will surface as runtime type errors, not compile-time
+ * errors — this is an intentional trade-off for a static phase graph without
+ * a dynamic type registry.
+ *
+ * @param deps       The resolved dependency map from the runner
+ * @param phaseName  The name of the upstream phase whose output you need
+ * @returns          The typed output of the phase
+ * @throws           If the phase is not found in the dependency map
+ */
+export function getPhaseOutput(deps, phaseName) {
+    const result = deps.get(phaseName);
+    if (!result) {
+        throw new Error(`Phase '${phaseName}' not found in resolved dependencies`);
+    }
+    return result.output;
+}

package/dist/core/ingestion/pipeline-phases/wildcard-synthesis.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Wildcard import binding synthesis.
+ *
+ * Languages with whole-module import semantics (Go, Ruby, C/C++, Swift)
+ * import all exported symbols from a file, not specific named symbols.
+ * After parsing, we know which symbols each file exports (via graph
+ * `isExported`), so we can expand IMPORTS edges into per-symbol bindings
+ * that the cross-file propagation phase can use for type resolution.
+ *
+ * Also builds Python module-alias maps for namespace-import languages
+ * (`import models` → `models.User()` resolves to `models.py:User`).
+ *
+ * @module
+ */
+import type { KnowledgeGraph } from '../../graph/types.js';
+import type { createResolutionContext } from '../model/resolution-context.js';
+import type { SupportedLanguages } from '../../../_shared/index.js';
+/** Check if a language uses wildcard (whole-module) import semantics. */
+export declare function isWildcardImportLanguage(lang: SupportedLanguages): boolean;
+/** Check if a language needs synthesis before call resolution.
+ *  True for wildcard-import languages AND namespace-import languages (Python). */
+export declare function needsSynthesis(lang: SupportedLanguages): boolean;
+/**
+ * Strategy implementation for `importSemantics: 'wildcard-transitive'` (C, C++).
+ *
+ * Textual-include languages chain symbols through files: if `dict.c` includes
+ * `server.h` and `server.h` includes `dict.h`, then `dict.c` sees symbols from
+ * all three files. This helper walks the include graph (combining both the
+ * ingestion-context `importMap` and the graph-level IMPORTS edges) until the
+ * closure is stable.
+ *
+ * **Order matters.** The returned `Set` preserves iteration order (insertion
+ * order). `synthesizeWildcardImportBindings` dedupes bindings by symbol name
+ * on a first-seen-wins basis, so this closure's ordering determines which
+ * declaration wins when multiple headers export the same name (e.g. overloaded
+ * free functions like `write_audit()` vs `write_audit(const char*)` in
+ * different headers). We therefore:
+ *   1. Seed the closure with direct imports in declaration order (matches the
+ *      order of `#include` directives in the source file).
+ *   2. Use FIFO / true BFS (`queue.shift()`) for transitive expansion, so
+ *      closer headers are seen before deeper ones.
+ *
+ * Cycle-safe: the `closure.has(file)` guard prevents infinite loops on circular
+ * header includes, which are valid C/C++ when paired with `#pragma once` or
+ * include guards.
+ *
+ * Size-bounded: the closure is capped at `MAX_TRANSITIVE_CLOSURE_SIZE` files to
+ * prevent OOM on pathological codebases (e.g. boost, monoheader kernel code)
+ * where one translation unit can transitively reach tens of thousands of
+ * headers. Partial closures still yield useful bindings for the cluster of
+ * headers closest to the importer, which is what overload resolution and
+ * cross-file call resolution care about.
+ *
+ * Queue implementation: uses a head-index over a growing array (O(1) dequeue)
+ * instead of `Array.prototype.shift()` (O(n)) so deep chains stay linear.
+ */
+export declare function expandTransitiveIncludeClosure(directImports: Iterable<string>, importMap: ReadonlyMap<string, ReadonlySet<string>>, graphImports: ReadonlyMap<string, ReadonlySet<string>>): Set<string>;
+/**
+ * Synthesize namedImportMap entries for languages with whole-module imports.
+ *
+ * For each file that imports another file via wildcard semantics:
+ * 1. Look up all exported symbols from the imported file (via graph nodes)
+ * 2. Create synthetic named bindings: `{ name → { sourcePath, exportedName } }`
+ * 3. Build Python module-alias maps for namespace-import languages
+ *
+ * @param graph  The knowledge graph with parsed symbol nodes
+ * @param ctx    Resolution context with importMap and namedImportMap
+ * @returns      Number of synthetic bindings created
+ */
+export declare function synthesizeWildcardImportBindings(graph: KnowledgeGraph, ctx: ReturnType<typeof createResolutionContext>): number;