gitnexus 1.6.3-rc.9 → 1.6.3

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

@@ -3,6 +3,38 @@
  *
  * Type definitions for the embedding generation and semantic search system.
  */
+export declare const LABEL_FUNCTION: "Function";
+export declare const LABEL_METHOD: "Method";
+export declare const LABEL_CONSTRUCTOR: "Constructor";
+export declare const LABEL_CLASS: "Class";
+export declare const LABEL_INTERFACE: "Interface";
+export declare const LABEL_STRUCT: "Struct";
+export declare const LABEL_ENUM: "Enum";
+export declare const LABEL_TRAIT: "Trait";
+export declare const LABEL_IMPL: "Impl";
+export declare const LABEL_MACRO: "Macro";
+export declare const LABEL_NAMESPACE: "Namespace";
+export declare const LABEL_TYPE_ALIAS: "TypeAlias";
+export declare const LABEL_TYPEDEF: "Typedef";
+export declare const LABEL_CONST: "Const";
+export declare const LABEL_PROPERTY: "Property";
+export declare const LABEL_RECORD: "Record";
+export declare const LABEL_UNION: "Union";
+export declare const LABEL_STATIC: "Static";
+export declare const LABEL_VARIABLE: "Variable";
+export declare const LABEL_CODE_ELEMENT: "CodeElement";
+export declare const CHUNK_MODE_AST_FUNCTION: "ast-function";
+export declare const CHUNK_MODE_AST_DECLARATION: "ast-declaration";
+export declare const CHUNK_MODE_CHARACTER: "character";
+export declare const STRUCTURAL_TEXT_MODE_NONE: "none";
+export declare const STRUCTURAL_TEXT_MODE_DECLARATION: "declaration";
+export interface ChunkingRule {
+    mode: typeof CHUNK_MODE_AST_FUNCTION | typeof CHUNK_MODE_AST_DECLARATION | typeof CHUNK_MODE_CHARACTER;
+    includePrefix: boolean;
+    includeSuffix: boolean;
+    groupFields: boolean;
+    structuralTextMode: typeof STRUCTURAL_TEXT_MODE_NONE | typeof STRUCTURAL_TEXT_MODE_DECLARATION;
+}
 /**
  * Node labels that need chunking (have code body, potentially long)
  */
@@ -29,13 +61,22 @@ export declare const isChunkableLabel: (label: string) => boolean;
  */
 export declare const isShortLabel: (label: string) => boolean;
 /**
- * Node labels that have structural names (methods/fields) extractable via AST
+ * Node labels that have structural names (methods/fields) extractable via AST.
+ * Only labels that consume methodNames/fieldNames in their embedding text should
+ * be listed here — extra entries trigger wasted AST parses with no effect on output.
  */
 export declare const STRUCTURAL_LABELS: ReadonlySet<string>;
 /**
  * Node labels that have isExported column in their schema
  */
 export declare const LABELS_WITH_EXPORTED: ReadonlySet<string>;
+/**
+ * Labels that need special chunking and/or structural text semantics.
+ * Any chunkable label omitted here intentionally falls back to characterChunk
+ * plus generateCodeBodyText (for example Enum/Trait/Impl/Macro/Namespace).
+ */
+type ChunkableLabel = (typeof CHUNKABLE_LABELS)[number];
+export declare const CHUNKING_RULES: Readonly<Partial<Record<ChunkableLabel, ChunkingRule>>>;
 /**
  * Embedding pipeline phases
  */
@@ -163,3 +204,4 @@ export declare const dedupBestChunks: (rows: ChunkSearchRow[], limit?: number) =
  * or can tell the result set is exhausted.
  */
 export declare const collectBestChunks: (limit: number, fetchRows: (fetchLimit: number) => Promise<ChunkSearchRow[]>, maxFetch?: number) => Promise<Map<string, BestChunkMatch>>;
+export {};

package/dist/core/embeddings/types.js

@@ -3,34 +3,61 @@
  *
  * Type definitions for the embedding generation and semantic search system.
  */
+export const LABEL_FUNCTION = 'Function';
+export const LABEL_METHOD = 'Method';
+export const LABEL_CONSTRUCTOR = 'Constructor';
+export const LABEL_CLASS = 'Class';
+export const LABEL_INTERFACE = 'Interface';
+export const LABEL_STRUCT = 'Struct';
+export const LABEL_ENUM = 'Enum';
+export const LABEL_TRAIT = 'Trait';
+export const LABEL_IMPL = 'Impl';
+export const LABEL_MACRO = 'Macro';
+export const LABEL_NAMESPACE = 'Namespace';
+export const LABEL_TYPE_ALIAS = 'TypeAlias';
+export const LABEL_TYPEDEF = 'Typedef';
+export const LABEL_CONST = 'Const';
+export const LABEL_PROPERTY = 'Property';
+export const LABEL_RECORD = 'Record';
+export const LABEL_UNION = 'Union';
+export const LABEL_STATIC = 'Static';
+export const LABEL_VARIABLE = 'Variable';
+export const LABEL_CODE_ELEMENT = 'CodeElement';
+export const CHUNK_MODE_AST_FUNCTION = 'ast-function';
+export const CHUNK_MODE_AST_DECLARATION = 'ast-declaration';
+// CHUNK_MODE_CHARACTER exists for type completeness but is a no-op in CHUNKING_RULES —
+// omit the entry entirely to get character fallback via chunker.ts dispatch.
+export const CHUNK_MODE_CHARACTER = 'character';
+export const STRUCTURAL_TEXT_MODE_NONE = 'none';
+export const STRUCTURAL_TEXT_MODE_DECLARATION = 'declaration';
 /**
  * Node labels that need chunking (have code body, potentially long)
  */
 export const CHUNKABLE_LABELS = [
-    'Function',
-    'Method',
-    'Constructor',
-    'Class',
-    'Interface',
-    'Struct',
-    'Enum',
-    'Trait',
-    'Impl',
-    'Macro',
-    'Namespace',
+    LABEL_FUNCTION,
+    LABEL_METHOD,
+    LABEL_CONSTRUCTOR,
+    LABEL_CLASS,
+    LABEL_INTERFACE,
+    LABEL_STRUCT,
+    LABEL_ENUM,
+    LABEL_TRAIT,
+    LABEL_IMPL,
+    LABEL_MACRO,
+    LABEL_NAMESPACE,
 ];
 /**
  * Node labels that are short (no chunking needed, embed directly)
  */
 export const SHORT_LABELS = [
-    'TypeAlias',
-    'Typedef',
-    'Const',
-    'Property',
-    'Record',
-    'Union',
-    'Static',
-    'Variable',
+    LABEL_TYPE_ALIAS,
+    LABEL_TYPEDEF,
+    LABEL_CONST,
+    LABEL_PROPERTY,
+    LABEL_RECORD,
+    LABEL_UNION,
+    LABEL_STATIC,
+    LABEL_VARIABLE,
 ];
 /**
  * All embeddable labels (union of CHUNKABLE + SHORT)
@@ -49,24 +76,69 @@ export const isChunkableLabel = (label) => CHUNKABLE_LABELS.includes(label);
  */
 export const isShortLabel = (label) => SHORT_LABELS.includes(label);
 /**
- * Node labels that have structural names (methods/fields) extractable via AST
+ * Node labels that have structural names (methods/fields) extractable via AST.
+ * Only labels that consume methodNames/fieldNames in their embedding text should
+ * be listed here — extra entries trigger wasted AST parses with no effect on output.
  */
 export const STRUCTURAL_LABELS = new Set([
-    'Class',
-    'Struct',
-    'Interface',
-    'Enum',
+    LABEL_CLASS,
+    LABEL_STRUCT,
+    LABEL_INTERFACE,
 ]);
 /**
  * Node labels that have isExported column in their schema
  */
 export const LABELS_WITH_EXPORTED = new Set([
-    'Function',
-    'Class',
-    'Interface',
-    'Method',
-    'CodeElement',
+    LABEL_FUNCTION,
+    LABEL_CLASS,
+    LABEL_INTERFACE,
+    LABEL_METHOD,
+    LABEL_CODE_ELEMENT,
 ]);
+export const CHUNKING_RULES = {
+    [LABEL_FUNCTION]: {
+        mode: CHUNK_MODE_AST_FUNCTION,
+        includePrefix: true,
+        includeSuffix: true,
+        groupFields: false,
+        structuralTextMode: STRUCTURAL_TEXT_MODE_NONE,
+    },
+    [LABEL_METHOD]: {
+        mode: CHUNK_MODE_AST_FUNCTION,
+        includePrefix: true,
+        includeSuffix: true,
+        groupFields: false,
+        structuralTextMode: STRUCTURAL_TEXT_MODE_NONE,
+    },
+    [LABEL_CONSTRUCTOR]: {
+        mode: CHUNK_MODE_AST_FUNCTION,
+        includePrefix: true,
+        includeSuffix: true,
+        groupFields: false,
+        structuralTextMode: STRUCTURAL_TEXT_MODE_NONE,
+    },
+    [LABEL_CLASS]: {
+        mode: CHUNK_MODE_AST_DECLARATION,
+        includePrefix: true,
+        includeSuffix: false,
+        groupFields: true,
+        structuralTextMode: STRUCTURAL_TEXT_MODE_DECLARATION,
+    },
+    [LABEL_INTERFACE]: {
+        mode: CHUNK_MODE_AST_DECLARATION,
+        includePrefix: true,
+        includeSuffix: false,
+        groupFields: false,
+        structuralTextMode: STRUCTURAL_TEXT_MODE_DECLARATION,
+    },
+    [LABEL_STRUCT]: {
+        mode: CHUNK_MODE_AST_DECLARATION,
+        includePrefix: true,
+        includeSuffix: false,
+        groupFields: true,
+        structuralTextMode: STRUCTURAL_TEXT_MODE_DECLARATION,
+    },
+};
 /**
  * Default embedding configuration
  * Uses snowflake-arctic-embed-xs for browser efficiency

package/dist/core/git-staleness.d.ts

@@ -2,6 +2,7 @@
  * Git working tree vs index commit staleness (used by MCP resources, group status, etc.).
  * Lives in core/ so application code does not depend on the MCP package layer.
  */
+import { type CwdMatch } from '../storage/repo-manager.js';
 export interface StalenessInfo {
     isStale: boolean;
     commitsBehind: number;
@@ -11,3 +12,20 @@ export interface StalenessInfo {
  * Check how many commits the index is behind HEAD (synchronous; uses git CLI).
  */
 export declare function checkStaleness(repoPath: string, lastCommit: string): StalenessInfo;
+/**
+ * Resolve a working directory against the global registry. Returns:
+ *   - `match: 'path'`              when `cwd` is inside a registered entry's path
+ *   - `match: 'sibling-by-remote'` when `cwd` lives in a different on-disk clone
+ *                                   of the same repo (same `remoteUrl`)
+ *   - `match: 'none'`              when neither match applies
+ *
+ * For sibling-by-remote matches, the caller's HEAD and the drift vs the
+ * indexed `lastCommit` are also returned so the MCP layer can warn
+ * before serving silently-stale answers (issue: silent graph drift
+ * across sibling clones).
+ *
+ * `path` matches deliberately use the longest-prefix rule so a cwd
+ * inside a sub-path of a registered repo still matches that repo, not
+ * a coincidentally-aliased shorter entry.
+ */
+export declare function checkCwdMatch(cwd: string): Promise<CwdMatch>;

package/dist/core/git-staleness.js

@@ -3,6 +3,9 @@
  * Lives in core/ so application code does not depend on the MCP package layer.
  */
 import { execFileSync } from 'node:child_process';
+import path from 'path';
+import { readRegistry } from '../storage/repo-manager.js';
+import { getGitRoot, getCurrentCommit, getRemoteUrl } from '../storage/git.js';
 /**
  * Check how many commits the index is behind HEAD (synchronous; uses git CLI).
  */
@@ -27,3 +30,108 @@ export function checkStaleness(repoPath, lastCommit) {
         return { isStale: false, commitsBehind: 0 };
     }
 }
+/**
+ * Compare a sibling-clone HEAD against an indexed `lastCommit`. Returns
+ * `undefined` when the indexed commit is not reachable from the sibling
+ * (e.g. divergent branches, shallow clone, missing ref). The caller
+ * should treat `undefined` as "drift unknown" rather than "no drift".
+ */
+function commitsAheadOfIndexed(siblingPath, indexedCommit) {
+    if (!indexedCommit)
+        return undefined;
+    try {
+        const result = execFileSync('git', ['rev-list', '--count', `${indexedCommit}..HEAD`], {
+            cwd: siblingPath,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        return parseInt(result, 10) || 0;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolve a working directory against the global registry. Returns:
+ *   - `match: 'path'`              when `cwd` is inside a registered entry's path
+ *   - `match: 'sibling-by-remote'` when `cwd` lives in a different on-disk clone
+ *                                   of the same repo (same `remoteUrl`)
+ *   - `match: 'none'`              when neither match applies
+ *
+ * For sibling-by-remote matches, the caller's HEAD and the drift vs the
+ * indexed `lastCommit` are also returned so the MCP layer can warn
+ * before serving silently-stale answers (issue: silent graph drift
+ * across sibling clones).
+ *
+ * `path` matches deliberately use the longest-prefix rule so a cwd
+ * inside a sub-path of a registered repo still matches that repo, not
+ * a coincidentally-aliased shorter entry.
+ */
+export async function checkCwdMatch(cwd) {
+    const entries = await readRegistry();
+    if (entries.length === 0)
+        return { match: 'none' };
+    const isWin = process.platform === 'win32';
+    const norm = (p) => (isWin ? path.resolve(p).toLowerCase() : path.resolve(p));
+    const sep = path.sep;
+    const cwdResolved = path.resolve(cwd);
+    const cwdNorm = norm(cwdResolved);
+    // 1) Path-based match (longest prefix wins, boundary-safe).
+    let bestPath;
+    let bestLen = -1;
+    for (const e of entries) {
+        const p = norm(e.path);
+        if (cwdNorm === p || cwdNorm.startsWith(p + sep)) {
+            if (p.length > bestLen) {
+                bestPath = e;
+                bestLen = p.length;
+            }
+        }
+    }
+    if (bestPath)
+        return { match: 'path', entry: bestPath };
+    // 2) Sibling-by-remote: locate the cwd's git root, get its remote
+    //    URL, and look for any registered entry with the same fingerprint.
+    const cwdGitRoot = getGitRoot(cwdResolved);
+    if (!cwdGitRoot)
+        return { match: 'none' };
+    const cwdRemote = getRemoteUrl(cwdGitRoot);
+    if (!cwdRemote)
+        return { match: 'none' };
+    const sibling = entries.find((e) => e.remoteUrl === cwdRemote && norm(e.path) !== norm(cwdGitRoot));
+    if (!sibling)
+        return { match: 'none' };
+    const cwdHead = getCurrentCommit(cwdGitRoot) || undefined;
+    const drift = commitsAheadOfIndexed(cwdGitRoot, sibling.lastCommit);
+    // Same commit on both clones → still report match=sibling-by-remote
+    // (the relationship is real and useful to callers like list_repos /
+    // future tooling) but leave `hint` unset: there's nothing to warn
+    // about, and `maybeWarnSiblingDrift` already short-circuits this
+    // case independently. Surfacing a no-op hint would force callers
+    // to second-guess whether they need to display it.
+    let hint;
+    if (cwdHead && cwdHead === sibling.lastCommit) {
+        hint = undefined;
+    }
+    else if (drift && drift > 0) {
+        hint =
+            `⚠️ Index for "${sibling.name}" was built at ${sibling.path}; ` +
+                `your cwd (${cwdGitRoot}) is a sibling clone that is ${drift} commit${drift > 1 ? 's' : ''} ` +
+                `ahead of the indexed commit. Results may be stale or incorrect — re-run \`gitnexus analyze\` ` +
+                `to refresh the index.`;
+    }
+    else {
+        hint =
+            `⚠️ Index for "${sibling.name}" was built at ${sibling.path}; ` +
+                `your cwd (${cwdGitRoot}) is a sibling clone whose HEAD differs from the indexed commit. ` +
+                `Results may be stale or incorrect — re-run \`gitnexus analyze\` to refresh the index.`;
+    }
+    return {
+        match: 'sibling-by-remote',
+        entry: sibling,
+        cwdGitRoot,
+        cwdHead,
+        drift,
+        hint,
+    };
+}

package/dist/core/graph/graph.js

@@ -1,28 +1,113 @@
+/** Fresh empty iterator per call — `[].values()` returns a new
+ *  exhausted iterator each invocation, so empty-type lookups don't
+ *  share a single already-exhausted iterator across callers. */
+function emptyRelIter() {
+    return [].values();
+}
 export const createKnowledgeGraph = () => {
     const nodeMap = new Map();
     const relationshipMap = new Map();
+    // Per-type index maintained alongside `relationshipMap`. Bucket
+    // values are `Map<id, Relationship>` so per-type iteration is cheap
+    // and per-edge removal is O(1). See plan
+    // docs/plans/2026-04-20-002-perf-parse-heritage-mro-plan.md (Unit 1).
+    const relationshipsByType = new Map();
+    // Reverse-adjacency index: nodeId → Set<relId> of every edge where
+    // this node appears as source OR target. Maintained on writeRel /
+    // deleteRel so `removeNode` can delete a node's edges in
+    // O(edges-touching-node) instead of O(total-edges).
+    const edgeIdsByNode = new Map();
+    // File index: filePath → Set<nodeId>. Maintained on addNode /
+    // removeNode so `removeNodesByFile` reaches its file's nodes
+    // directly instead of scanning the whole node map.
+    const nodeIdsByFile = new Map();
+    // Private helpers that encode the dual-index invariants in one
+    // place. All mutation paths go through these — adding a new
+    // mutation method only needs to call the helper, not remember to
+    // touch every index.
+    const addToBucket = (map, key, value) => {
+        let bucket = map.get(key);
+        if (bucket === undefined) {
+            bucket = new Set();
+            map.set(key, bucket);
+        }
+        bucket.add(value);
+    };
+    const removeFromBucket = (map, key, value) => {
+        const bucket = map.get(key);
+        if (bucket === undefined)
+            return;
+        bucket.delete(value);
+        if (bucket.size === 0)
+            map.delete(key);
+    };
+    const writeRel = (rel) => {
+        relationshipMap.set(rel.id, rel);
+        let typeBucket = relationshipsByType.get(rel.type);
+        if (typeBucket === undefined) {
+            typeBucket = new Map();
+            relationshipsByType.set(rel.type, typeBucket);
+        }
+        typeBucket.set(rel.id, rel);
+        addToBucket(edgeIdsByNode, rel.sourceId, rel.id);
+        // Guard against a self-edge writing the same rel.id into the
+        // same Set twice — Set dedup handles it, but we skip explicitly
+        // for clarity.
+        if (rel.targetId !== rel.sourceId) {
+            addToBucket(edgeIdsByNode, rel.targetId, rel.id);
+        }
+    };
+    const deleteRel = (rel) => {
+        relationshipMap.delete(rel.id);
+        const typeBucket = relationshipsByType.get(rel.type);
+        if (typeBucket !== undefined) {
+            typeBucket.delete(rel.id);
+            if (typeBucket.size === 0)
+                relationshipsByType.delete(rel.type);
+        }
+        removeFromBucket(edgeIdsByNode, rel.sourceId, rel.id);
+        if (rel.targetId !== rel.sourceId) {
+            removeFromBucket(edgeIdsByNode, rel.targetId, rel.id);
+        }
+    };
     const addNode = (node) => {
-        if (!nodeMap.has(node.id)) {
-            nodeMap.set(node.id, node);
+        if (nodeMap.has(node.id))
+            return;
+        nodeMap.set(node.id, node);
+        const filePath = node.properties?.filePath;
+        if (typeof filePath === 'string' && filePath.length > 0) {
+            addToBucket(nodeIdsByFile, filePath, node.id);
         }
     };
     const addRelationship = (relationship) => {
-        if (!relationshipMap.has(relationship.id)) {
-            relationshipMap.set(relationship.id, relationship);
-        }
+        if (relationshipMap.has(relationship.id))
+            return;
+        writeRel(relationship);
     };
     /**
-     * Remove a single node and all relationships involving it
+     * Remove a single node and all relationships involving it.
+     * O(edges-touching-node) via the reverse-adjacency index — no full
+     * relationshipMap scan.
      */
     const removeNode = (nodeId) => {
-        if (!nodeMap.has(nodeId))
+        const node = nodeMap.get(nodeId);
+        if (node === undefined)
             return false;
         nodeMap.delete(nodeId);
-        // Remove all relationships involving this node
-        for (const [relId, rel] of relationshipMap) {
-            if (rel.sourceId === nodeId || rel.targetId === nodeId) {
-                relationshipMap.delete(relId);
+        const filePath = node.properties?.filePath;
+        if (typeof filePath === 'string' && filePath.length > 0) {
+            removeFromBucket(nodeIdsByFile, filePath, nodeId);
+        }
+        const touchingEdgeIds = edgeIdsByNode.get(nodeId);
+        if (touchingEdgeIds !== undefined) {
+            // Snapshot the ids before iterating — deleteRel mutates the same
+            // Set via removeFromBucket, which would break mid-loop iteration.
+            for (const relId of [...touchingEdgeIds]) {
+                const rel = relationshipMap.get(relId);
+                if (rel !== undefined)
+                    deleteRel(rel);
             }
+            edgeIdsByNode.delete(nodeId);
         }
         return true;
     };
@@ -31,20 +116,26 @@ export const createKnowledgeGraph = () => {
      * Returns true if the relationship existed and was removed, false otherwise.
      */
     const removeRelationship = (relationshipId) => {
-        return relationshipMap.delete(relationshipId);
+        const rel = relationshipMap.get(relationshipId);
+        if (rel === undefined)
+            return false;
+        deleteRel(rel);
+        return true;
     };
     /**
      * Remove all nodes (and their relationships) belonging to a file.
+     * O(file-nodes × avg-edges-per-node) via the file index — no full
+     * node-map scan.
      */
     const removeNodesByFile = (filePath) => {
-        let removed = 0;
-        for (const [nodeId, node] of nodeMap) {
-            if (node.properties?.filePath === filePath) {
-                removeNode(nodeId);
-                removed++;
-            }
-        }
-        return removed;
+        const nodeIds = nodeIdsByFile.get(filePath);
+        if (nodeIds === undefined)
+            return 0;
+        // Snapshot before iterating — removeNode mutates nodeIdsByFile.
+        const snapshot = [...nodeIds];
+        for (const nodeId of snapshot)
+            removeNode(nodeId);
+        return snapshot.length;
     };
     return {
         get nodes() {
@@ -55,6 +146,10 @@ export const createKnowledgeGraph = () => {
         },
         iterNodes: () => nodeMap.values(),
         iterRelationships: () => relationshipMap.values(),
+        iterRelationshipsByType: (type) => {
+            const bucket = relationshipsByType.get(type);
+            return bucket === undefined ? emptyRelIter() : bucket.values();
+        },
         forEachNode(fn) {
             nodeMap.forEach(fn);
         },

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

@@ -6,12 +6,23 @@
  *
  * This file only defines the CLI's KnowledgeGraph with mutation methods.
  */
-import type { GraphNode, GraphRelationship } from '../../_shared/index.js';
+import type { GraphNode, GraphRelationship, RelationshipType } from '../../_shared/index.js';
 export interface KnowledgeGraph {
     nodes: GraphNode[];
     relationships: GraphRelationship[];
     iterNodes: () => IterableIterator<GraphNode>;
     iterRelationships: () => IterableIterator<GraphRelationship>;
+    /**
+     * Iterate ONLY relationships of the given type, backed by a per-type
+     * index maintained in `addRelationship` / `removeRelationship` /
+     * `removeNode` / `removeNodesByFile`. Returns an empty iterator when
+     * the graph contains no relationships of that type.
+     *
+     * Prefer this over `iterRelationships()` + per-edge type filtering
+     * for hot paths (MRO setup, heritage walks). Backwards-compatible:
+     * existing `iterRelationships()` callers keep working.
+     */
+    iterRelationshipsByType: (type: RelationshipType) => IterableIterator<GraphRelationship>;
     forEachNode: (fn: (node: GraphNode) => void) => void;
     forEachRelationship: (fn: (rel: GraphRelationship) => void) => void;
     getNode: (id: string) => GraphNode | undefined;

package/dist/core/group/config-parser.d.ts

@@ -1,3 +1,7 @@
 import type { GroupConfig } from './types.js';
 export declare function parseGroupConfig(yamlContent: string): GroupConfig;
+export declare class GroupNotFoundError extends Error {
+    readonly groupName: string;
+    constructor(groupName: string);
+}
 export declare function loadGroupConfig(groupDir: string): Promise<GroupConfig>;

package/dist/core/group/config-parser.js

@@ -74,10 +74,27 @@ export function parseGroupConfig(yamlContent) {
         matching,
     };
 }
+export class GroupNotFoundError extends Error {
+    groupName;
+    constructor(groupName) {
+        super(`Group "${groupName}" not found`);
+        this.groupName = groupName;
+        this.name = 'GroupNotFoundError';
+    }
+}
 export async function loadGroupConfig(groupDir) {
     const fsp = await import('node:fs/promises');
     const path = await import('node:path');
     const yamlPath = path.join(groupDir, 'group.yaml');
-    const content = await fsp.readFile(yamlPath, 'utf-8');
+    let content;
+    try {
+        content = await fsp.readFile(yamlPath, 'utf-8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            throw new GroupNotFoundError(path.basename(groupDir));
+        }
+        throw err;
+    }
     return parseGroupConfig(content);
 }

package/dist/core/group/cross-impact.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Cross-repo impact (Phase 1 local walk + Phase 2 bridge fan-out).
+ * All bridge Cypher for this feature lives in this module.
+ */
+import type { GroupImpactResult } from './types.js';
+import type { GroupToolPort } from './service.js';
+/** Cross-boundary hops beyond this value are clamped (multi-hop reserved for future work). */
+export declare const MAX_SUPPORTED_CROSS_DEPTH = 1;
+/** Default wall-clock budget for the Phase 1 `impact` leg when callers omit `timeoutMs`. */
+export declare const DEFAULT_LOCAL_IMPACT_TIMEOUT_MS = 30000;
+export interface RunGroupImpactDeps {
+    port: GroupToolPort;
+    gitnexusDir: string;
+}
+export declare function validateGroupImpactParams(params: Record<string, unknown>): {
+    ok: true;
+    name: string;
+    repoPath: string;
+    target: string;
+    direction: 'upstream' | 'downstream';
+    maxDepth: number;
+    crossDepth: number;
+    crossDepthWarning?: string;
+    relationTypes?: string[];
+    includeTests: boolean;
+    minConfidence: number;
+    service?: string;
+    subgroup?: string;
+    timeoutMs: number;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function collectImpactSymbolUids(local: unknown, servicePrefix: string | undefined): {
+    uids: string[];
+    targetFilePath?: string;
+};
+export declare function runGroupImpact(deps: RunGroupImpactDeps, params: Record<string, unknown>): Promise<GroupImpactResult | {
+    error: string;
+}>;
+export { normalizeServicePrefix, fileMatchesServicePrefix } from './group-path-utils.js';