gitnexus 1.5.2 → 1.6.0

package/dist/core/group/storage.d.ts

@@ -0,0 +1,9 @@
+import type { ContractRegistry } from './types.js';
+export declare function getDefaultGitnexusDir(): string;
+export declare function getGroupsBaseDir(gitnexusDir?: string): string;
+export declare function validateGroupName(name: string): void;
+export declare function getGroupDir(gitnexusDir: string, groupName: string): string;
+export declare function writeContractRegistry(groupDir: string, registry: ContractRegistry): Promise<void>;
+export declare function readContractRegistry(groupDir: string): Promise<ContractRegistry | null>;
+export declare function listGroups(gitnexusDir?: string): Promise<string[]>;
+export declare function createGroupDir(gitnexusDir: string, groupName: string, force?: boolean): Promise<string>;

package/dist/core/group/storage.js

@@ -0,0 +1,91 @@
+import * as fs from 'node:fs';
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import * as os from 'node:os';
+const CONTRACTS_FILE = 'contracts.json';
+export function getDefaultGitnexusDir() {
+    return process.env.GITNEXUS_HOME || path.join(os.homedir(), '.gitnexus');
+}
+export function getGroupsBaseDir(gitnexusDir) {
+    return path.join(gitnexusDir || getDefaultGitnexusDir(), 'groups');
+}
+const GROUP_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/;
+export function validateGroupName(name) {
+    if (!GROUP_NAME_RE.test(name)) {
+        throw new Error(`Invalid group name "${name}". Names must start with a letter or digit and contain only [a-zA-Z0-9_-].`);
+    }
+}
+export function getGroupDir(gitnexusDir, groupName) {
+    validateGroupName(groupName);
+    return path.join(gitnexusDir, 'groups', groupName);
+}
+export async function writeContractRegistry(groupDir, registry) {
+    const targetPath = path.join(groupDir, CONTRACTS_FILE);
+    const tmpPath = `${targetPath}.tmp.${Date.now()}`;
+    await fsp.writeFile(tmpPath, JSON.stringify(registry, null, 2), 'utf-8');
+    await fsp.rename(tmpPath, targetPath);
+}
+export async function readContractRegistry(groupDir) {
+    const filePath = path.join(groupDir, CONTRACTS_FILE);
+    try {
+        const content = await fsp.readFile(filePath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+}
+export async function listGroups(gitnexusDir) {
+    const groupsDir = getGroupsBaseDir(gitnexusDir);
+    try {
+        const entries = await fsp.readdir(groupsDir, { withFileTypes: true });
+        const names = [];
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                const yamlPath = path.join(groupsDir, entry.name, 'group.yaml');
+                if (fs.existsSync(yamlPath)) {
+                    names.push(entry.name);
+                }
+            }
+        }
+        return names;
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+}
+export async function createGroupDir(gitnexusDir, groupName, force = false) {
+    const groupDir = getGroupDir(gitnexusDir, groupName);
+    if (fs.existsSync(path.join(groupDir, 'group.yaml')) && !force) {
+        throw new Error(`Group "${groupName}" already exists. Use --force to overwrite.`);
+    }
+    await fsp.mkdir(groupDir, { recursive: true });
+    const template = `version: 1
+name: ${groupName}
+description: ""
+
+repos: {}
+
+links: []
+
+packages: {}
+
+detect:
+  http: true
+  grpc: true
+  topics: true
+  shared_libs: true
+  embedding_fallback: true
+
+matching:
+  bm25_threshold: 0.7
+  embedding_threshold: 0.65
+  max_candidates_per_step: 3
+`;
+    await fsp.writeFile(path.join(groupDir, 'group.yaml'), template, 'utf-8');
+    return groupDir;
+}

package/dist/core/group/sync.d.ts

@@ -0,0 +1,21 @@
+import { type RegistryEntry } from '../../storage/repo-manager.js';
+import type { GroupConfig, RepoHandle, RepoSnapshot, StoredContract, CrossLink } from './types.js';
+export interface SyncOptions {
+    extractorOverride?: ((repo: RepoHandle) => Promise<StoredContract[]>) | (() => Promise<StoredContract[]>);
+    resolveRepoHandle?: (registryName: string, groupPath: string) => Promise<RepoHandle | null>;
+    skipWrite?: boolean;
+    groupDir?: string;
+    allowStale?: boolean;
+    verbose?: boolean;
+    exactOnly?: boolean;
+    skipEmbeddings?: boolean;
+}
+export interface SyncResult {
+    contracts: StoredContract[];
+    crossLinks: CrossLink[];
+    unmatched: StoredContract[];
+    missingRepos: string[];
+    repoSnapshots: Record<string, RepoSnapshot>;
+}
+export declare function stableRepoPoolId(entry: RegistryEntry, allEntries: RegistryEntry[]): string;
+export declare function syncGroup(config: GroupConfig, opts?: SyncOptions): Promise<SyncResult>;

package/dist/core/group/sync.js

@@ -0,0 +1,148 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { Buffer } from 'node:buffer';
+import { initLbug, closeLbug, executeParameterized } from '../lbug/pool-adapter.js';
+import { readRegistry } from '../../storage/repo-manager.js';
+import { HttpRouteExtractor } from './extractors/http-route-extractor.js';
+import { GrpcExtractor } from './extractors/grpc-extractor.js';
+import { TopicExtractor } from './extractors/topic-extractor.js';
+import { runExactMatch } from './matching.js';
+import { detectServiceBoundaries, assignService } from './service-boundary-detector.js';
+import { writeContractRegistry } from './storage.js';
+export function stableRepoPoolId(entry, allEntries) {
+    const base = entry.name.toLowerCase();
+    const resolved = path.resolve(entry.path);
+    for (const other of allEntries) {
+        if (other.name.toLowerCase() === base && path.resolve(other.path) !== resolved) {
+            const hash = Buffer.from(entry.path).toString('base64url').slice(0, 6);
+            return `${base}-${hash}`;
+        }
+    }
+    return base;
+}
+function defaultResolveHandle(allEntries) {
+    return async (registryName, groupPath) => {
+        const e = allEntries.find((en) => en.name === registryName);
+        if (!e)
+            return null;
+        const poolId = stableRepoPoolId(e, allEntries);
+        return {
+            id: poolId,
+            path: groupPath,
+            repoPath: e.path,
+            storagePath: e.storagePath,
+        };
+    };
+}
+export async function syncGroup(config, opts) {
+    const missingRepos = [];
+    const repoSnapshots = {};
+    let autoContracts = [];
+    let dbExecutors;
+    const eo = opts?.extractorOverride;
+    if (eo && eo.length === 0) {
+        autoContracts = await eo();
+    }
+    else {
+        const entries = await readRegistry();
+        const resolve = opts?.resolveRepoHandle ?? defaultResolveHandle(entries);
+        const httpEx = new HttpRouteExtractor();
+        const grpcEx = new GrpcExtractor();
+        const topicEx = new TopicExtractor();
+        dbExecutors = new Map();
+        const openPoolIds = [];
+        try {
+            for (const [groupPath, regName] of Object.entries(config.repos)) {
+                const handle = await resolve(regName, groupPath);
+                if (!handle) {
+                    missingRepos.push(groupPath);
+                    continue;
+                }
+                const poolId = handle.id;
+                const lbugPath = path.join(handle.storagePath, 'lbug');
+                try {
+                    await initLbug(poolId, lbugPath);
+                    openPoolIds.push(poolId);
+                    const executor = (query, params) => executeParameterized(poolId, query, params ?? {});
+                    dbExecutors.set(groupPath, executor);
+                    const boundaries = await detectServiceBoundaries(handle.repoPath);
+                    if (config.detect.http) {
+                        const extracted = await httpEx.extract(executor, handle.repoPath, handle);
+                        for (const c of extracted) {
+                            autoContracts.push({
+                                ...c,
+                                repo: groupPath,
+                                service: assignService(c.symbolRef.filePath, boundaries),
+                            });
+                        }
+                    }
+                    if (config.detect.grpc) {
+                        const extracted = await grpcEx.extract(executor, handle.repoPath, handle);
+                        for (const c of extracted) {
+                            autoContracts.push({
+                                ...c,
+                                repo: groupPath,
+                                service: assignService(c.symbolRef.filePath, boundaries),
+                            });
+                        }
+                    }
+                    if (config.detect.topics) {
+                        const extracted = await topicEx.extract(executor, handle.repoPath, handle);
+                        for (const c of extracted) {
+                            autoContracts.push({
+                                ...c,
+                                repo: groupPath,
+                                service: assignService(c.symbolRef.filePath, boundaries),
+                            });
+                        }
+                    }
+                    const metaPath = path.join(handle.storagePath, 'meta.json');
+                    try {
+                        const raw = await fs.readFile(metaPath, 'utf-8');
+                        const m = JSON.parse(raw);
+                        repoSnapshots[groupPath] = {
+                            indexedAt: m.indexedAt || '',
+                            lastCommit: m.lastCommit || '',
+                        };
+                    }
+                    catch {
+                        const e = entries.find((en) => en.name === regName);
+                        repoSnapshots[groupPath] = {
+                            indexedAt: e?.indexedAt || '',
+                            lastCommit: e?.lastCommit || '',
+                        };
+                    }
+                }
+                catch {
+                    missingRepos.push(groupPath);
+                }
+            }
+        }
+        finally {
+            for (const id of [...new Set(openPoolIds)]) {
+                await closeLbug(id).catch(() => { });
+            }
+        }
+    }
+    const { matched, unmatched } = runExactMatch(autoContracts);
+    const crossLinks = matched;
+    const allContracts = autoContracts;
+    const registry = {
+        version: 1,
+        generatedAt: new Date().toISOString(),
+        repoSnapshots,
+        missingRepos,
+        contracts: allContracts,
+        crossLinks,
+    };
+    if (opts?.groupDir && !opts.skipWrite) {
+        await writeContractRegistry(opts.groupDir, registry);
+    }
+    return {
+        contracts: allContracts,
+        crossLinks,
+        unmatched,
+        missingRepos,
+        repoSnapshots,
+    };
+}

package/dist/core/group/types.d.ts

@@ -0,0 +1,130 @@
+export type ContractType = 'http' | 'grpc' | 'topic' | 'lib' | 'custom';
+export type MatchType = 'exact' | 'manifest' | 'wildcard' | 'bm25' | 'embedding';
+export type ContractRole = 'provider' | 'consumer';
+export interface GroupConfig {
+    version: number;
+    name: string;
+    description: string;
+    repos: Record<string, string>;
+    links: GroupManifestLink[];
+    packages: Record<string, Record<string, string>>;
+    detect: DetectConfig;
+    matching: MatchingConfig;
+}
+export interface GroupManifestLink {
+    from: string;
+    to: string;
+    type: ContractType;
+    contract: string;
+    role: ContractRole;
+}
+export interface DetectConfig {
+    http: boolean;
+    grpc: boolean;
+    topics: boolean;
+    shared_libs: boolean;
+    embedding_fallback: boolean;
+}
+export interface MatchingConfig {
+    bm25_threshold: number;
+    embedding_threshold: number;
+    max_candidates_per_step: number;
+}
+export interface SymbolRef {
+    filePath: string;
+    name: string;
+}
+export interface ExtractedContract {
+    contractId: string;
+    type: ContractType;
+    role: ContractRole;
+    symbolUid: string;
+    symbolRef: SymbolRef;
+    symbolName: string;
+    confidence: number;
+    meta: Record<string, unknown>;
+    /** Service boundary within a monorepo (relative path from repo root, e.g. "services/auth"). */
+    service?: string;
+}
+export interface CrossLinkEndpoint {
+    repo: string;
+    /** Service boundary within a monorepo (relative path from repo root). */
+    service?: string;
+    symbolUid: string;
+    symbolRef: SymbolRef;
+}
+export interface CrossLink {
+    from: CrossLinkEndpoint;
+    to: CrossLinkEndpoint;
+    type: ContractType;
+    contractId: string;
+    matchType: MatchType;
+    confidence: number;
+}
+export interface RepoSnapshot {
+    indexedAt: string;
+    lastCommit: string;
+}
+export interface ContractRegistry {
+    version: number;
+    generatedAt: string;
+    repoSnapshots: Record<string, RepoSnapshot>;
+    missingRepos: string[];
+    contracts: StoredContract[];
+    crossLinks: CrossLink[];
+}
+export interface StoredContract extends ExtractedContract {
+    repo: string;
+}
+/** Repo within a group (group path + paths; name collision with MCP RepoHandle — import from group/types only). */
+export interface RepoHandle {
+    id: string;
+    path: string;
+    repoPath: string;
+    storagePath: string;
+}
+export interface GroupImpactResult {
+    local: unknown;
+    group: string;
+    cross: CrossRepoImpact[];
+    outOfScope: OutOfScopeLink[];
+    truncated: boolean;
+    truncatedRepos: string[];
+    summary: {
+        direct: number;
+        processes_affected: number;
+        modules_affected: number;
+        cross_repo_hits: number;
+    };
+    risk: string;
+}
+export interface CrossRepoImpact {
+    repo: string;
+    repo_path: string;
+    contract: {
+        id: string;
+        type: ContractType;
+        match_type: MatchType;
+        confidence: number;
+    };
+    by_depth: Record<string, unknown[]>;
+    affected_processes: string[];
+}
+export interface OutOfScopeLink {
+    from: string;
+    to: string;
+    contractId: string;
+    confidence: number;
+}
+/** Opaque handle to an open bridge LadybugDB. */
+export interface BridgeHandle {
+    /** Internal — do not access directly. */
+    readonly _db: unknown;
+    readonly _conn: unknown;
+    readonly groupDir: string;
+}
+export interface BridgeMeta {
+    version: number;
+    generatedAt: string;
+    missingRepos: string[];
+}

package/dist/core/group/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/ingestion/binding-accumulator.d.ts

@@ -0,0 +1,207 @@
+/**
+ * BindingAccumulator — read-append-only accumulator that collects TypeEnv
+ * bindings across files in the GitNexus analyzer pipeline.
+ *
+ * **Current behavior (both execution paths):** The accumulator carries only
+ * file-scope (`scope = ''`) entries. Function-scope bindings are stripped
+ * at both write sites:
+ *
+ * - **Worker path**: `parse-worker.ts` serializes only
+ *   `typeEnv.fileScope()` entries across the IPC boundary.
+ * - **Sequential path**: `type-env.ts::flush()` iterates only the FILE_SCOPE
+ *   entry of the env map and writes `BindingEntry` records with
+ *   `scope: ''` hardcoded.
+ *
+ * The narrowing exists because function-scope bindings have zero downstream
+ * consumers today and were previously costing ~4.9 MB of heap + IPC on
+ * every pipeline run. See `type-env.ts::flush()` and the `FileScopeBindings`
+ * JSDoc in `parse-worker.ts` for the paired Phase 9 reversion checklist.
+ *
+ * **Historical quality asymmetry (Phase 9 consideration):** Even though
+ * both paths now carry only file-scope data, the two paths were built
+ * under different resolution capabilities, and a future Phase 9 reverter
+ * that widens them back to all scopes will inherit that asymmetry:
+ *
+ * - **Sequential path** had (and would regain) access to the full
+ *   `SymbolTable` and `importedBindings`, so its bindings benefit from
+ *   Tier 2 cross-file propagation.
+ * - **Worker path** runs without `SymbolTable` / `importedBindings` and
+ *   can only produce Tier 0 (annotation-declared) and local Tier 1
+ *   (same-file constructor inference) bindings.
+ *
+ * Phase 9 consumers that trust every entry equally will silently produce
+ * worse results for large repos (worker-dominant) than small ones
+ * (sequential-dominant). If Phase 9 needs homogeneous quality, either
+ * (a) tag entries with their tier at insert time so consumers can filter,
+ * or (b) post-process worker-path entries through a follow-up resolution
+ * pass after the main-thread `SymbolTable` is complete.
+ *
+ * **Lifecycle contract**: `append → finalize → consume → dispose`. See
+ * `finalize()` and `dispose()` for the state machine. Disposal is
+ * orthogonal to finalization: either order is legal.
+ */
+export interface BindingEntry {
+    readonly scope: string;
+    readonly varName: string;
+    readonly typeName: string;
+}
+/**
+ * Minimal graph-node shape required by `enrichExportedTypeMap()`. Intentionally
+ * narrower than the full `GraphNode` type in `graph/types.ts` so tests can
+ * construct a minimal mock without depending on the full graph module, and
+ * so the enrichment logic is a pure function over this contract.
+ *
+ * Matches the shape of the real `KnowledgeGraph` node's `properties.isExported`
+ * access path — tests that use a different shape silently pass while
+ * production fails.
+ */
+export interface EnrichmentGraphNode {
+    readonly id: string;
+    readonly properties?: {
+        readonly isExported?: boolean;
+    } | undefined;
+}
+/**
+ * Minimal graph lookup interface used by `enrichExportedTypeMap()`.
+ * Consumes only the method the enrichment loop actually calls.
+ */
+export interface EnrichmentGraphLookup {
+    getNode(id: string): EnrichmentGraphNode | undefined;
+}
+/**
+ * Merge file-scope bindings from a (finalized) `BindingAccumulator` into an
+ * `exportedTypeMap` for symbols whose graph nodes are marked as exported.
+ *
+ * This is the single source of truth for the worker-path ExportedTypeMap
+ * enrichment loop. Previously the logic lived inline in `pipeline.ts` and
+ * the test suite reimplemented it as a `runEnrichmentLoop` helper — a
+ * drift-prone pattern that meant tests could pass while production regressed.
+ * Extracting it here makes the production code call the same function the
+ * tests call.
+ *
+ * **Node ID candidate order**: `Function:{filePath}:{name}` →
+ * `Variable:{filePath}:{name}` → `Const:{filePath}:{name}`. First match wins.
+ *
+ * **Tier 0 priority**: if `exportedTypeMap` already has an entry for a
+ * `(filePath, name)` pair, the accumulator entry does NOT overwrite it —
+ * the SymbolTable tier-0 pass is authoritative. Without this guard, a
+ * worker-path binding could clobber a higher-quality type from SymbolTable.
+ *
+ * **Finalize precondition**: the accumulator should be finalized before
+ * calling this function. The lifecycle contract is
+ * `append → finalize → enrich → dispose`. Finalization is not asserted
+ * here (the test suite and pipeline both honor it separately), but any
+ * append happening concurrently with this enrichment would be a lifecycle
+ * bug at the caller level.
+ *
+ * @returns The number of new entries written into `exportedTypeMap`
+ *          (0 on empty accumulator or when every candidate was filtered
+ *          out by the export check or the Tier 0 guard).
+ */
+export declare function enrichExportedTypeMap(bindingAccumulator: BindingAccumulator, graph: EnrichmentGraphLookup, exportedTypeMap: Map<string, Map<string, string>>): number;
+export declare class BindingAccumulator {
+    private readonly _allByFile;
+    private readonly _fileScopeByFile;
+    private _totalBindings;
+    private _finalized;
+    private _disposed;
+    /**
+     * Append bindings for a file. Safe to call multiple times for the same file.
+     * Throws if the accumulator has been finalized. Skips if entries is empty.
+     *
+     * The `entries` parameter is `readonly` — this method never mutates the
+     * caller's array. Internally, the first `appendFile` call per filePath
+     * makes a defensive copy (`slice()`), and subsequent calls push into the
+     * accumulator's own storage.
+     */
+    appendFile(filePath: string, entries: readonly BindingEntry[]): void;
+    /** Lock the accumulator — no further appends. Idempotent. */
+    finalize(): void;
+    /**
+     * Release the accumulator's heap footprint. Clears both internal storage
+     * maps and resets `_totalBindings` to zero. Idempotent and orthogonal to
+     * `finalize()` — calling `dispose()` does not change the finalized state.
+     *
+     * Post-dispose contract: all read methods return empty/undefined state
+     * matching a never-appended-to accumulator. Specifically:
+     *   - `fileCount === 0`
+     *   - `totalBindings === 0`
+     *   - `files()` yields an empty iterator
+     *   - `getFile(x)` returns `undefined` for all `x`
+     *   - `fileScopeEntries(x)` returns `[]` for all `x`
+     *   - `estimateMemoryBytes()` returns `0`
+     *
+     * If `dispose()` is called **before** `finalize()`, subsequent `appendFile`
+     * calls succeed — the accumulator behaves like a fresh one. If called
+     * **after** `finalize()`, subsequent `appendFile` calls throw the existing
+     * "finalized" error.
+     *
+     * Lifecycle note: the pipeline disposes the accumulator after both Phase 9
+     * consumers (`processCallsFromExtracted`, `processAssignmentsFromExtracted`)
+     * and the ExportedTypeMap enrichment loop have completed, so the heap is
+     * released before Phase 14 (`runCrossFileBindingPropagation`) and
+     * `runGraphAnalysisPhases` begin their long-running work.
+     */
+    dispose(): void;
+    /** Get all bindings for a file, or undefined if the file is unknown. */
+    getFile(filePath: string): readonly BindingEntry[] | undefined;
+    /**
+     * Get only scope='' (file-level) entries as [varName, typeName] tuples.
+     * For iteration-based consumers (e.g., `enrichExportedTypeMap`).
+     * Returns an empty array for an unknown file.
+     *
+     * O(1) map lookup + O(n_file_scope) tuple reconstruction from the inner
+     * Map. Does NOT walk function-scope entries.
+     *
+     * For point-lookup consumers (e.g., Phase 9 fallback), prefer
+     * `fileScopeGet(filePath, name)` — O(1) with no allocation.
+     */
+    fileScopeEntries(filePath: string): readonly (readonly [string, string])[];
+    /**
+     * O(1) point-lookup for a single file-scope binding by (filePath, name).
+     * Returns the typeName if found, `undefined` otherwise.
+     *
+     * This is the preferred lookup path for Phase 9 consumers that resolve
+     * a single callee's return type — avoids the O(n_file_scope) iteration
+     * and defensive-copy allocation of `fileScopeEntries()`.
+     */
+    fileScopeGet(filePath: string, name: string): string | undefined;
+    /** Iterate over all file paths in insertion order. */
+    files(): IterableIterator<string>;
+    /** Number of distinct files with at least one binding. */
+    get fileCount(): number;
+    /** Total number of binding entries across all files. */
+    get totalBindings(): number;
+    /** Whether the accumulator has been finalized. */
+    get finalized(): boolean;
+    /**
+     * Whether the accumulator has been disposed. Exposed for symmetry with
+     * `finalized` so debug tooling and future Phase 9 consumers can detect a
+     * disposed accumulator without inspecting empty state heuristically.
+     *
+     * Disposal and finalization are orthogonal: a disposed accumulator may or
+     * may not be finalized, and vice versa. See `dispose()` for the full
+     * lifecycle contract.
+     */
+    get disposed(): boolean;
+    /**
+     * Rough memory estimate in bytes (intentionally pessimistic).
+     * Formula: sum of (ENTRY_OVERHEAD + char bytes of scope+varName+typeName) per entry
+     *          + MAP_ENTRY_OVERHEAD + char bytes of filePath per file.
+     *
+     * Note: V8 stores all-ASCII strings as Latin-1 (1 byte/char) and only upgrades
+     * to UCS-2 (2 bytes/char) for non-Latin-1 code points. Source paths and type names
+     * are typically all-ASCII, so actual heap cost is roughly half what this returns.
+     * The pessimistic factor is intentional — better to over-budget than under-budget.
+     *
+     * **⚠ Cost profile**: O(totalBindings) — iterates every entry in
+     * `_allByFile` and reads three string `.length` properties per entry.
+     * At a typical repo scale (10k files × ~20 file-scope bindings) this is
+     * ~200k property reads per call. Call at most once per pipeline run,
+     * NOT per file, per chunk, or per progress tick. The current single
+     * call site is the dev-mode telemetry log at the pipeline finalize
+     * seam. Adding a per-file-progress caller would silently make it
+     * quadratic in repo size.
+     */
+    estimateMemoryBytes(): number;
+}