arceus-s 1.6.4

package/dist/core/embeddings/types.js

@@ -0,0 +1,202 @@
+/**
+ * Embedding Pipeline Types
+ *
+ * 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 = [
+    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 = [
+    LABEL_TYPE_ALIAS,
+    LABEL_TYPEDEF,
+    LABEL_CONST,
+    LABEL_PROPERTY,
+    LABEL_RECORD,
+    LABEL_UNION,
+    LABEL_STATIC,
+    LABEL_VARIABLE,
+];
+/**
+ * All embeddable labels (union of CHUNKABLE + SHORT)
+ */
+export const EMBEDDABLE_LABELS = [...CHUNKABLE_LABELS, ...SHORT_LABELS];
+/**
+ * Check if a label should be embedded
+ */
+export const isEmbeddableLabel = (label) => EMBEDDABLE_LABELS.includes(label);
+/**
+ * Check if a label needs chunking
+ */
+export const isChunkableLabel = (label) => CHUNKABLE_LABELS.includes(label);
+/**
+ * Check if a label is a short type (no chunking)
+ */
+export const isShortLabel = (label) => SHORT_LABELS.includes(label);
+/**
+ * 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([
+    LABEL_CLASS,
+    LABEL_STRUCT,
+    LABEL_INTERFACE,
+]);
+/**
+ * Node labels that have isExported column in their schema
+ */
+export const LABELS_WITH_EXPORTED = new Set([
+    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
+ * Tries WebGPU first (fast), user can choose WASM fallback if unavailable
+ */
+export const DEFAULT_EMBEDDING_CONFIG = {
+    modelId: 'Snowflake/snowflake-arctic-embed-xs',
+    batchSize: 16,
+    subBatchSize: 8,
+    threads: 2,
+    dimensions: 384,
+    device: 'auto',
+    maxSnippetLength: 500,
+    chunkSize: 1200,
+    overlap: 120,
+    maxDescriptionLength: 150,
+};
+/**
+ * Deduplicate vector search chunk results by nodeId,
+ * keeping the chunk with smallest distance for each node.
+ */
+export const dedupBestChunks = (rows, limit) => {
+    const best = new Map();
+    for (const row of rows) {
+        const existing = best.get(row.nodeId);
+        if (!existing || row.distance < existing.distance) {
+            best.set(row.nodeId, {
+                chunkIndex: row.chunkIndex,
+                startLine: row.startLine,
+                endLine: row.endLine,
+                distance: row.distance,
+            });
+        }
+        if (limit !== undefined && best.size >= limit)
+            break;
+    }
+    return best;
+};
+const DEFAULT_FETCH_MULTIPLIER = 4;
+const DEFAULT_FETCH_BUFFER = 8;
+const DEFAULT_MAX_FETCH = 200;
+/**
+ * Fetch vector-search chunks until we have enough unique nodeIds
+ * or can tell the result set is exhausted.
+ */
+export const collectBestChunks = async (limit, fetchRows, maxFetch = DEFAULT_MAX_FETCH) => {
+    if (limit <= 0)
+        return new Map();
+    let fetchLimit = Math.max(limit * DEFAULT_FETCH_MULTIPLIER, limit + DEFAULT_FETCH_BUFFER);
+    let previousFetchLimit = 0;
+    while (fetchLimit > previousFetchLimit) {
+        const rows = await fetchRows(fetchLimit);
+        const bestChunks = dedupBestChunks(rows, limit);
+        if (bestChunks.size >= limit || rows.length < fetchLimit) {
+            return bestChunks;
+        }
+        previousFetchLimit = fetchLimit;
+        fetchLimit = fetchLimit >= maxFetch ? fetchLimit * 2 : Math.min(maxFetch, fetchLimit * 2);
+    }
+    return new Map();
+};

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

@@ -0,0 +1,37 @@
+/**
+ * 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;
+    hint?: string;
+}
+/**
+ * Check how many commits the index is behind HEAD (synchronous; uses git CLI).
+ */
+export declare function checkStaleness(repoPath: string, lastCommit: string): StalenessInfo;
+/**
+ * Async variant of {@link checkStaleness} — spawns git as a child process
+ * instead of blocking the event loop.  Used by `listRepos()` to check many
+ * repos in parallel (issue #1363: 200 repos × sync spawn ≈ 50 s).
+ */
+export declare function checkStalenessAsync(repoPath: string, lastCommit: string): Promise<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

@@ -0,0 +1,167 @@
+/**
+ * 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 { execFile, execFileSync } from 'node:child_process';
+import { promisify } from 'node:util';
+import path from 'path';
+import { readRegistry } from '../storage/repo-manager.js';
+import { findGitRootByDotGit, getCurrentCommit, getRemoteUrl } from '../storage/git.js';
+const execFileAsync = promisify(execFile);
+/**
+ * Check how many commits the index is behind HEAD (synchronous; uses git CLI).
+ */
+export function checkStaleness(repoPath, lastCommit) {
+    try {
+        const result = execFileSync('git', ['rev-list', '--count', `${lastCommit}..HEAD`], {
+            cwd: repoPath,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        const commitsBehind = parseInt(result, 10) || 0;
+        if (commitsBehind > 0) {
+            return {
+                isStale: true,
+                commitsBehind,
+                hint: `⚠️ Index is ${commitsBehind} commit${commitsBehind > 1 ? 's' : ''} behind HEAD. Run analyze tool to update.`,
+            };
+        }
+        return { isStale: false, commitsBehind: 0 };
+    }
+    catch {
+        return { isStale: false, commitsBehind: 0 };
+    }
+}
+/**
+ * Async variant of {@link checkStaleness} — spawns git as a child process
+ * instead of blocking the event loop.  Used by `listRepos()` to check many
+ * repos in parallel (issue #1363: 200 repos × sync spawn ≈ 50 s).
+ */
+export async function checkStalenessAsync(repoPath, lastCommit) {
+    try {
+        // Note: promisified execFile captures stdout/stderr by default (no stdio option needed,
+        // unlike the sync variant which requires explicit stdio: ['pipe','pipe','pipe']).
+        const { stdout } = await execFileAsync('git', ['rev-list', '--count', `${lastCommit}..HEAD`], {
+            cwd: repoPath,
+            encoding: 'utf-8',
+        });
+        const commitsBehind = parseInt(stdout.trim(), 10) || 0;
+        if (commitsBehind > 0) {
+            return {
+                isStale: true,
+                commitsBehind,
+                hint: `⚠️ Index is ${commitsBehind} commit${commitsBehind > 1 ? 's' : ''} behind HEAD. Run analyze tool to update.`,
+            };
+        }
+        return { isStale: false, commitsBehind: 0 };
+    }
+    catch {
+        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 using only ancestor
+    //    `.git` checks before shelling out. This keeps MCP startup from
+    //    running git in an unrelated launch cwd such as $HOME (#1138).
+    const cwdGitRoot = findGitRootByDotGit(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 \`arc 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 \`arc analyze\` to refresh the index.`;
+    }
+    return {
+        match: 'sibling-by-remote',
+        entry: sibling,
+        cwdGitRoot,
+        cwdHead,
+        drift,
+        hint,
+    };
+}

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

@@ -0,0 +1,2 @@
+import { KnowledgeGraph } from './types.js';
+export declare const createKnowledgeGraph: () => KnowledgeGraph;

package/dist/core/graph/graph.js

@@ -0,0 +1,173 @@
+/** 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))
+            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))
+            return;
+        writeRel(relationship);
+    };
+    /**
+     * 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) => {
+        const node = nodeMap.get(nodeId);
+        if (node === undefined)
+            return false;
+        nodeMap.delete(nodeId);
+        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;
+    };
+    /**
+     * Remove a single relationship by id.
+     * Returns true if the relationship existed and was removed, false otherwise.
+     */
+    const removeRelationship = (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) => {
+        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() {
+            return Array.from(nodeMap.values());
+        },
+        get relationships() {
+            return Array.from(relationshipMap.values());
+        },
+        iterNodes: () => nodeMap.values(),
+        iterRelationships: () => relationshipMap.values(),
+        iterRelationshipsByType: (type) => {
+            const bucket = relationshipsByType.get(type);
+            return bucket === undefined ? emptyRelIter() : bucket.values();
+        },
+        forEachNode(fn) {
+            nodeMap.forEach(fn);
+        },
+        forEachRelationship(fn) {
+            relationshipMap.forEach(fn);
+        },
+        getNode: (id) => nodeMap.get(id),
+        // O(1) count getters - avoid creating arrays just for length
+        get nodeCount() {
+            return nodeMap.size;
+        },
+        get relationshipCount() {
+            return relationshipMap.size;
+        },
+        addNode,
+        addRelationship,
+        removeNode,
+        removeNodesByFile,
+        removeRelationship,
+    };
+};

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

@@ -0,0 +1,36 @@
+/**
+ * CLI-specific graph types.
+ *
+ * Shared types (NodeLabel, GraphNode, etc.) should be imported
+ * directly from '../../_shared/index.js' at call sites.
+ *
+ * This file only defines the CLI's KnowledgeGraph with mutation methods.
+ */
+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;
+    nodeCount: number;
+    relationshipCount: number;
+    addNode: (node: GraphNode) => void;
+    addRelationship: (relationship: GraphRelationship) => void;
+    removeNode: (nodeId: string) => boolean;
+    removeNodesByFile: (filePath: string) => number;
+    removeRelationship: (relationshipId: string) => boolean;
+}

package/dist/core/graph/types.js

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