homegraph 0.9.9

package/dist/sync/worktree.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Git Worktree Awareness
+ *
+ * A CodeGraph index lives in a `.homegraph/` directory and is resolved by
+ * walking up parent directories to the nearest one (see
+ * `findNearestCodeGraphRoot`). That walk is unaware of git worktrees: when a
+ * worktree is created *inside* the main checkout (e.g. some tools place them
+ * under `.gitignore`d paths like `.claude/worktrees/<name>/`), a command run
+ * from the worktree walks up and silently resolves the MAIN checkout's index.
+ *
+ * Every query then returns results from the main tree's code — usually a
+ * different branch — rather than the worktree the user is actually editing.
+ * Symbols added or changed only in the worktree are invisible. This module
+ * detects that "borrowed index" situation so callers can warn about it.
+ *
+ * Detection is best-effort: when git is unavailable or the path isn't a repo,
+ * it reports "no mismatch" and callers carry on unchanged.
+ */
+/**
+ * Absolute, symlink-resolved toplevel of the git working tree that `dir`
+ * belongs to, or null when `dir` isn't inside a git repo (or git is missing).
+ *
+ * `git rev-parse --show-toplevel` returns the per-worktree root: the main
+ * checkout and each linked worktree report their own distinct directory, which
+ * is exactly the distinction this module relies on.
+ */
+export declare function gitWorktreeRoot(dir: string): string | null;
+export interface WorktreeIndexMismatch {
+    /** The git working tree the command was run from. */
+    worktreeRoot: string;
+    /** The (different) working tree whose `.homegraph` index is being used. */
+    indexRoot: string;
+}
+/**
+ * Detect when `startPath` lives in one git working tree but the resolved
+ * CodeGraph index (`indexRoot`) belongs to a *different* working tree.
+ *
+ * Returns null — meaning "nothing to warn about" — when:
+ *   - `startPath` isn't in a git repo (or git is unavailable),
+ *   - the index already lives in `startPath`'s own working tree, or
+ *   - `indexRoot` isn't itself a working-tree root (an unrelated parent dir
+ *     that merely happens to contain a `.homegraph/`), which keeps non-git
+ *     and monorepo-subdir layouts from producing false warnings.
+ */
+export declare function detectWorktreeIndexMismatch(startPath: string, indexRoot: string): WorktreeIndexMismatch | null;
+/** One-line-per-fact warning describing a detected mismatch. */
+export declare function worktreeMismatchWarning(m: WorktreeIndexMismatch): string;
+/**
+ * Compact, single-line variant for prefixing a tool's result. Read tools
+ * return their answer inline, so the heads-up has to ride on the same payload
+ * the agent is already reading — a multi-line block would bury the result.
+ */
+export declare function worktreeMismatchNotice(m: WorktreeIndexMismatch): string;
+//# sourceMappingURL=worktree.d.ts.map

package/dist/sync/worktree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree.d.ts","sourceRoot":"","sources":["../../src/sync/worktree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAY1D;AAED,MAAM,WAAW,qBAAqB;IACpC,qDAAqD;IACrD,YAAY,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CACzC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,qBAAqB,GAAG,IAAI,CAa9B;AAED,gEAAgE;AAChE,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,qBAAqB,GAAG,MAAM,CASxE;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,qBAAqB,GAAG,MAAM,CAOvE"}

package/dist/sync/worktree.js

@@ -0,0 +1,137 @@
+"use strict";
+/**
+ * Git Worktree Awareness
+ *
+ * A CodeGraph index lives in a `.homegraph/` directory and is resolved by
+ * walking up parent directories to the nearest one (see
+ * `findNearestCodeGraphRoot`). That walk is unaware of git worktrees: when a
+ * worktree is created *inside* the main checkout (e.g. some tools place them
+ * under `.gitignore`d paths like `.claude/worktrees/<name>/`), a command run
+ * from the worktree walks up and silently resolves the MAIN checkout's index.
+ *
+ * Every query then returns results from the main tree's code — usually a
+ * different branch — rather than the worktree the user is actually editing.
+ * Symbols added or changed only in the worktree are invisible. This module
+ * detects that "borrowed index" situation so callers can warn about it.
+ *
+ * Detection is best-effort: when git is unavailable or the path isn't a repo,
+ * it reports "no mismatch" and callers carry on unchanged.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gitWorktreeRoot = gitWorktreeRoot;
+exports.detectWorktreeIndexMismatch = detectWorktreeIndexMismatch;
+exports.worktreeMismatchWarning = worktreeMismatchWarning;
+exports.worktreeMismatchNotice = worktreeMismatchNotice;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+/**
+ * Absolute, symlink-resolved toplevel of the git working tree that `dir`
+ * belongs to, or null when `dir` isn't inside a git repo (or git is missing).
+ *
+ * `git rev-parse --show-toplevel` returns the per-worktree root: the main
+ * checkout and each linked worktree report their own distinct directory, which
+ * is exactly the distinction this module relies on.
+ */
+function gitWorktreeRoot(dir) {
+    try {
+        const out = (0, child_process_1.execFileSync)('git', ['rev-parse', '--show-toplevel'], {
+            cwd: dir,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            windowsHide: true,
+        }).trim();
+        return out ? realpath(out) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Detect when `startPath` lives in one git working tree but the resolved
+ * CodeGraph index (`indexRoot`) belongs to a *different* working tree.
+ *
+ * Returns null — meaning "nothing to warn about" — when:
+ *   - `startPath` isn't in a git repo (or git is unavailable),
+ *   - the index already lives in `startPath`'s own working tree, or
+ *   - `indexRoot` isn't itself a working-tree root (an unrelated parent dir
+ *     that merely happens to contain a `.homegraph/`), which keeps non-git
+ *     and monorepo-subdir layouts from producing false warnings.
+ */
+function detectWorktreeIndexMismatch(startPath, indexRoot) {
+    const worktreeRoot = gitWorktreeRoot(startPath);
+    if (!worktreeRoot)
+        return null;
+    const resolvedIndexRoot = realpath(indexRoot);
+    if (worktreeRoot === resolvedIndexRoot)
+        return null;
+    // Only flag it when the index root is itself a real working-tree root. This
+    // distinguishes "borrowed another worktree's index" from "index sits in a
+    // plain ancestor directory", and avoids warning outside git entirely.
+    if (gitWorktreeRoot(resolvedIndexRoot) !== resolvedIndexRoot)
+        return null;
+    return { worktreeRoot, indexRoot: resolvedIndexRoot };
+}
+/** One-line-per-fact warning describing a detected mismatch. */
+function worktreeMismatchWarning(m) {
+    return (`This CodeGraph index belongs to a different git working tree.\n` +
+        `  Running in: ${m.worktreeRoot}\n` +
+        `  Index from: ${m.indexRoot}\n` +
+        `Results reflect that tree's code (often a different branch), not this worktree — ` +
+        `symbols changed only here are missing. Run "homegraph init -i" in this worktree ` +
+        `for a worktree-local index.`);
+}
+/**
+ * Compact, single-line variant for prefixing a tool's result. Read tools
+ * return their answer inline, so the heads-up has to ride on the same payload
+ * the agent is already reading — a multi-line block would bury the result.
+ */
+function worktreeMismatchNotice(m) {
+    return (`⚠ CodeGraph results below come from a different git worktree (${m.indexRoot}), ` +
+        `not where you're working (${m.worktreeRoot}) — they may reflect another branch, ` +
+        `and symbols changed only here are missing. Run "homegraph init -i" here for a ` +
+        `worktree-local index.`);
+}
+/** Resolve symlinks where possible so tmp/realpath quirks don't break equality. */
+function realpath(p) {
+    try {
+        return fs.realpathSync(path.resolve(p));
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+//# sourceMappingURL=worktree.js.map

package/dist/sync/worktree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree.js","sourceRoot":"","sources":["../../src/sync/worktree.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAcH,0CAYC;AAoBD,kEAgBC;AAGD,0DASC;AAOD,wDAOC;AAtFD,uCAAyB;AACzB,2CAA6B;AAC7B,iDAA6C;AAE7C;;;;;;;GAOG;AACH,SAAgB,eAAe,CAAC,GAAW;IACzC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAA,4BAAY,EAAC,KAAK,EAAE,CAAC,WAAW,EAAE,iBAAiB,CAAC,EAAE;YAChE,GAAG,EAAE,GAAG;YACR,QAAQ,EAAE,MAAM;YAChB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC;YACnC,WAAW,EAAE,IAAI;SAClB,CAAC,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AASD;;;;;;;;;;GAUG;AACH,SAAgB,2BAA2B,CACzC,SAAiB,EACjB,SAAiB;IAEjB,MAAM,YAAY,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC;IAChD,IAAI,CAAC,YAAY;QAAE,OAAO,IAAI,CAAC;IAE/B,MAAM,iBAAiB,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;IAC9C,IAAI,YAAY,KAAK,iBAAiB;QAAE,OAAO,IAAI,CAAC;IAEpD,4EAA4E;IAC5E,0EAA0E;IAC1E,sEAAsE;IACtE,IAAI,eAAe,CAAC,iBAAiB,CAAC,KAAK,iBAAiB;QAAE,OAAO,IAAI,CAAC;IAE1E,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,iBAAiB,EAAE,CAAC;AACxD,CAAC;AAED,gEAAgE;AAChE,SAAgB,uBAAuB,CAAC,CAAwB;IAC9D,OAAO,CACL,iEAAiE;QACjE,iBAAiB,CAAC,CAAC,YAAY,IAAI;QACnC,iBAAiB,CAAC,CAAC,SAAS,IAAI;QAChC,mFAAmF;QACnF,kFAAkF;QAClF,6BAA6B,CAC9B,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAgB,sBAAsB,CAAC,CAAwB;IAC7D,OAAO,CACL,iEAAiE,CAAC,CAAC,SAAS,KAAK;QACjF,6BAA6B,CAAC,CAAC,YAAY,uCAAuC;QAClF,gFAAgF;QAChF,uBAAuB,CACxB,CAAC;AACJ,CAAC;AAED,mFAAmF;AACnF,SAAS,QAAQ,CAAC,CAAS;IACzB,IAAI,CAAC;QACH,OAAO,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACzB,CAAC;AACH,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,377 @@
+/**
+ * CodeGraph Type Definitions
+ *
+ * Core types for the semantic knowledge graph system.
+ */
+/**
+ * Types of nodes in the knowledge graph.
+ *
+ * Defined as a runtime-iterable `as const` array so the same source
+ * of truth backs both the TS type and any runtime validation
+ * (e.g. the search query parser).
+ */
+export declare const NODE_KINDS: readonly ["file", "module", "class", "struct", "interface", "trait", "protocol", "function", "method", "property", "field", "variable", "constant", "enum", "enum_member", "type_alias", "namespace", "parameter", "import", "export", "route", "component"];
+export type NodeKind = (typeof NODE_KINDS)[number];
+/**
+ * Types of edges (relationships) between nodes
+ */
+export type EdgeKind = 'contains' | 'calls' | 'imports' | 'exports' | 'extends' | 'implements' | 'references' | 'type_of' | 'returns' | 'instantiates' | 'overrides' | 'decorates';
+/**
+ * Supported programming languages. See NODE_KINDS for why this is a
+ * runtime-iterable const array.
+ */
+export declare const LANGUAGES: readonly ["arkts", "typescript", "javascript", "tsx", "jsx", "python", "go", "rust", "java", "c", "cpp", "csharp", "razor", "php", "ruby", "swift", "kotlin", "dart", "svelte", "vue", "liquid", "pascal", "scala", "lua", "luau", "objc", "yaml", "twig", "xml", "properties", "unknown"];
+export type Language = (typeof LANGUAGES)[number];
+/**
+ * A node in the knowledge graph representing a code symbol
+ */
+export interface Node {
+    /** Unique identifier (hash of file path + qualified name) */
+    id: string;
+    /** Type of code element */
+    kind: NodeKind;
+    /** Simple name (e.g., "calculateTotal") */
+    name: string;
+    /** Fully qualified name (e.g., "src/utils.ts::MathHelper.calculateTotal") */
+    qualifiedName: string;
+    /** File path relative to project root */
+    filePath: string;
+    /** Programming language */
+    language: Language;
+    /** Starting line number (1-indexed) */
+    startLine: number;
+    /** Ending line number (1-indexed) */
+    endLine: number;
+    /** Starting column (0-indexed) */
+    startColumn: number;
+    /** Ending column (0-indexed) */
+    endColumn: number;
+    /** Documentation string if present */
+    docstring?: string;
+    /** Function/method signature */
+    signature?: string;
+    /** Visibility modifier */
+    visibility?: 'public' | 'private' | 'protected' | 'internal';
+    /** Whether symbol is exported */
+    isExported?: boolean;
+    /** Whether symbol is async */
+    isAsync?: boolean;
+    /** Whether symbol is static */
+    isStatic?: boolean;
+    /** Whether symbol is abstract */
+    isAbstract?: boolean;
+    /** Decorators/annotations applied */
+    decorators?: string[];
+    /** Generic type parameters */
+    typeParameters?: string[];
+    /** When the node was last updated */
+    updatedAt: number;
+}
+/**
+ * An edge representing a relationship between two nodes
+ */
+export interface Edge {
+    /** Source node ID */
+    source: string;
+    /** Target node ID */
+    target: string;
+    /** Type of relationship */
+    kind: EdgeKind;
+    /** Additional context about the relationship */
+    metadata?: Record<string, unknown>;
+    /** Line number where relationship occurs (e.g., call site) */
+    line?: number;
+    /** Column number where relationship occurs */
+    column?: number;
+    /** How this edge was created */
+    provenance?: 'tree-sitter' | 'scip' | 'heuristic';
+}
+/**
+ * Metadata about a tracked file
+ */
+export interface FileRecord {
+    /** File path relative to project root */
+    path: string;
+    /** Content hash for change detection */
+    contentHash: string;
+    /** Detected language */
+    language: Language;
+    /** File size in bytes */
+    size: number;
+    /** Last modification timestamp */
+    modifiedAt: number;
+    /** When last indexed */
+    indexedAt: number;
+    /** Number of nodes extracted */
+    nodeCount: number;
+    /** Any extraction errors */
+    errors?: ExtractionError[];
+}
+/**
+ * Result from parsing a source file
+ */
+export interface ExtractionResult {
+    /** Extracted nodes */
+    nodes: Node[];
+    /** Extracted edges */
+    edges: Edge[];
+    /** References that couldn't be resolved yet */
+    unresolvedReferences: UnresolvedReference[];
+    /** Any errors during extraction */
+    errors: ExtractionError[];
+    /** Extraction duration in milliseconds */
+    durationMs: number;
+}
+/**
+ * Error during code extraction
+ */
+export interface ExtractionError {
+    /** Error message */
+    message: string;
+    /** File path where the error occurred */
+    filePath?: string;
+    /** Line number if available */
+    line?: number;
+    /** Column number if available */
+    column?: number;
+    /** Error severity */
+    severity: 'error' | 'warning';
+    /** Error code for categorization */
+    code?: string;
+}
+/**
+ * A reference that couldn't be resolved during extraction
+ */
+export interface UnresolvedReference {
+    /** ID of the node containing the reference */
+    fromNodeId: string;
+    /** Name being referenced */
+    referenceName: string;
+    /** Type of reference (call, type, import, etc.) */
+    referenceKind: EdgeKind;
+    /** Location of the reference */
+    line: number;
+    column: number;
+    /** File path where reference occurs (denormalized for performance) */
+    filePath?: string;
+    /** Language of the source file (denormalized for performance) */
+    language?: Language;
+    /** Possible qualified names it might resolve to */
+    candidates?: string[];
+}
+/**
+ * A subgraph containing a subset of the knowledge graph
+ */
+export interface Subgraph {
+    /** Nodes in this subgraph */
+    nodes: Map<string, Node>;
+    /** Edges in this subgraph */
+    edges: Edge[];
+    /** Root node IDs (entry points) */
+    roots: string[];
+    /**
+     * Retrieval confidence for context-style queries. `'low'` means the query
+     * resolved only to isolated common-word matches (no entry point corroborated
+     * by 2+ distinct query terms) — callers should surface an honest handoff to
+     * explore/trace rather than present the results as comprehensive. Undefined
+     * for graph traversals that don't run the search-ranking path.
+     */
+    confidence?: 'high' | 'low';
+}
+/**
+ * Options for graph traversal
+ */
+export interface TraversalOptions {
+    /** Maximum depth to traverse (default: Infinity) */
+    maxDepth?: number;
+    /** Edge types to follow (default: all) */
+    edgeKinds?: EdgeKind[];
+    /** Node types to include (default: all) */
+    nodeKinds?: NodeKind[];
+    /** Direction of traversal */
+    direction?: 'outgoing' | 'incoming' | 'both';
+    /** Maximum nodes to return */
+    limit?: number;
+    /** Whether to include the starting node */
+    includeStart?: boolean;
+}
+/**
+ * Options for searching the graph
+ */
+export interface SearchOptions {
+    /** Node types to search */
+    kinds?: NodeKind[];
+    /** Languages to include */
+    languages?: Language[];
+    /** File path patterns to include */
+    includePatterns?: string[];
+    /** File path patterns to exclude */
+    excludePatterns?: string[];
+    /** Maximum results to return */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+    /** Whether search is case-sensitive */
+    caseSensitive?: boolean;
+}
+/**
+ * A search result with relevance scoring
+ */
+export interface SearchResult {
+    /** Matching node */
+    node: Node;
+    /** Relevance score (0-1) */
+    score: number;
+    /** Matched text snippets for highlighting */
+    highlights?: string[];
+}
+/**
+ * Context information for code understanding
+ */
+export interface Context {
+    /** Primary node being examined */
+    focal: Node;
+    /** Nodes containing the focal node (file, class, etc.) */
+    ancestors: Node[];
+    /** Nodes directly contained by focal node */
+    children: Node[];
+    /** Incoming references (who calls/uses this) */
+    incomingRefs: Array<{
+        node: Node;
+        edge: Edge;
+    }>;
+    /** Outgoing references (what this calls/uses) */
+    outgoingRefs: Array<{
+        node: Node;
+        edge: Edge;
+    }>;
+    /** Related type information */
+    types: Node[];
+    /** Relevant imports */
+    imports: Node[];
+}
+/**
+ * A block of code with context
+ */
+export interface CodeBlock {
+    /** The code content */
+    content: string;
+    /** File path */
+    filePath: string;
+    /** Starting line */
+    startLine: number;
+    /** Ending line */
+    endLine: number;
+    /** Language for syntax highlighting */
+    language: Language;
+    /** Associated node if extracted */
+    node?: Node;
+}
+/**
+ * Database schema version info
+ */
+export interface SchemaVersion {
+    /** Current schema version */
+    version: number;
+    /** When schema was created/updated */
+    appliedAt: number;
+    /** Description of this version */
+    description?: string;
+}
+/**
+ * Statistics about the knowledge graph
+ */
+export interface GraphStats {
+    /** Total number of nodes */
+    nodeCount: number;
+    /** Total number of edges */
+    edgeCount: number;
+    /** Number of tracked files */
+    fileCount: number;
+    /** Node counts by kind */
+    nodesByKind: Record<NodeKind, number>;
+    /** Edge counts by kind */
+    edgesByKind: Record<EdgeKind, number>;
+    /** File counts by language */
+    filesByLanguage: Record<Language, number>;
+    /** Database size in bytes */
+    dbSizeBytes: number;
+    /** Last update timestamp */
+    lastUpdated: number;
+}
+/**
+ * Input for building task context
+ */
+export type TaskInput = string | {
+    title: string;
+    description?: string;
+};
+/**
+ * Options for building task context
+ */
+export interface BuildContextOptions {
+    /** Maximum number of nodes to include (default: 50) */
+    maxNodes?: number;
+    /** Maximum number of code blocks to include (default: 10) */
+    maxCodeBlocks?: number;
+    /** Maximum characters per code block (default: 2000) */
+    maxCodeBlockSize?: number;
+    /** Whether to include code blocks (default: true) */
+    includeCode?: boolean;
+    /** Output format (default: 'markdown') */
+    format?: 'markdown' | 'json';
+    /** Number of semantic search results (default: 5) */
+    searchLimit?: number;
+    /** Graph traversal depth from entry points (default: 2) */
+    traversalDepth?: number;
+    /** Minimum semantic similarity score (default: 0.3) */
+    minScore?: number;
+}
+/**
+ * Full context for a task, ready for Claude
+ */
+export interface TaskContext {
+    /** The original query/task */
+    query: string;
+    /** Subgraph of relevant nodes and edges */
+    subgraph: Subgraph;
+    /** Entry point nodes (from semantic search) */
+    entryPoints: Node[];
+    /** Code blocks extracted from key nodes */
+    codeBlocks: CodeBlock[];
+    /** Files involved in this context */
+    relatedFiles: string[];
+    /** Brief summary of the context */
+    summary: string;
+    /** Statistics about the context */
+    stats: {
+        /** Number of nodes included */
+        nodeCount: number;
+        /** Number of edges included */
+        edgeCount: number;
+        /** Number of files touched */
+        fileCount: number;
+        /** Number of code blocks included */
+        codeBlockCount: number;
+        /** Total characters in code blocks */
+        totalCodeSize: number;
+    };
+}
+/**
+ * Options for finding relevant context
+ */
+export interface FindRelevantContextOptions {
+    /** Number of semantic search results (default: 5) */
+    searchLimit?: number;
+    /** Graph traversal depth (default: 2) */
+    traversalDepth?: number;
+    /** Maximum nodes in result (default: 50) */
+    maxNodes?: number;
+    /** Minimum semantic similarity score (default: 0.3) */
+    minScore?: number;
+    /** Edge types to follow in traversal */
+    edgeKinds?: EdgeKind[];
+    /** Node types to include */
+    nodeKinds?: NodeKind[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * CodeGraph Type Definitions
+ *
+ * Core types for the semantic knowledge graph system.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LANGUAGES = exports.NODE_KINDS = void 0;
+// =============================================================================
+// Union Types
+// =============================================================================
+/**
+ * Types of nodes in the knowledge graph.
+ *
+ * Defined as a runtime-iterable `as const` array so the same source
+ * of truth backs both the TS type and any runtime validation
+ * (e.g. the search query parser).
+ */
+exports.NODE_KINDS = [
+    'file',
+    'module',
+    'class',
+    'struct',
+    'interface',
+    'trait',
+    'protocol',
+    'function',
+    'method',
+    'property',
+    'field',
+    'variable',
+    'constant',
+    'enum',
+    'enum_member',
+    'type_alias',
+    'namespace',
+    'parameter',
+    'import',
+    'export',
+    'route',
+    'component',
+];
+/**
+ * Supported programming languages. See NODE_KINDS for why this is a
+ * runtime-iterable const array.
+ */
+exports.LANGUAGES = [
+    'arkts',
+    'typescript',
+    'javascript',
+    'tsx',
+    'jsx',
+    'python',
+    'go',
+    'rust',
+    'java',
+    'c',
+    'cpp',
+    'csharp',
+    'razor',
+    'php',
+    'ruby',
+    'swift',
+    'kotlin',
+    'dart',
+    'svelte',
+    'vue',
+    'liquid',
+    'pascal',
+    'scala',
+    'lua',
+    'luau',
+    'objc',
+    'yaml',
+    'twig',
+    'xml',
+    'properties',
+    'unknown',
+];
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAEH,gFAAgF;AAChF,cAAc;AACd,gFAAgF;AAEhF;;;;;;GAMG;AACU,QAAA,UAAU,GAAG;IACxB,MAAM;IACN,QAAQ;IACR,OAAO;IACP,QAAQ;IACR,WAAW;IACX,OAAO;IACP,UAAU;IACV,UAAU;IACV,QAAQ;IACR,UAAU;IACV,OAAO;IACP,UAAU;IACV,UAAU;IACV,MAAM;IACN,aAAa;IACb,YAAY;IACZ,WAAW;IACX,WAAW;IACX,QAAQ;IACR,QAAQ;IACR,OAAO;IACP,WAAW;CACH,CAAC;AAqBX;;;GAGG;AACU,QAAA,SAAS,GAAG;IACvB,OAAO;IACP,YAAY;IACZ,YAAY;IACZ,KAAK;IACL,KAAK;IACL,QAAQ;IACR,IAAI;IACJ,MAAM;IACN,MAAM;IACN,GAAG;IACH,KAAK;IACL,QAAQ;IACR,OAAO;IACP,KAAK;IACL,MAAM;IACN,OAAO;IACP,QAAQ;IACR,MAAM;IACN,QAAQ;IACR,KAAK;IACL,QAAQ;IACR,QAAQ;IACR,OAAO;IACP,KAAK;IACL,MAAM;IACN,MAAM;IACN,MAAM;IACN,MAAM;IACN,KAAK;IACL,YAAY;IACZ,SAAS;CACD,CAAC"}