@saluzi/codegraph 0.1.0 → 0.2.1

package/dist/types.d.ts

@@ -10,424 +10,406 @@
  * 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]
+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'
+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 [
-  'typescript',
-  'javascript',
-  'tsx',
-  'jsx',
-  'python',
-  'go',
-  'rust',
-  'java',
-  'c',
-  'cpp',
-  'csharp',
-  'php',
-  'ruby',
-  'swift',
-  'kotlin',
-  'dart',
-  'svelte',
-  'vue',
-  'liquid',
-  'pascal',
-  'scala',
-  'lua',
-  'luau',
-  'yaml',
-  'twig',
-  'unknown',
-]
-export type Language = (typeof LANGUAGES)[number]
+export declare const LANGUAGES: readonly ["typescript", "javascript", "tsx", "jsx", "arkts", "python", "go", "rust", "java", "c", "cpp", "csharp", "razor", "php", "ruby", "swift", "kotlin", "dart", "svelte", "vue", "astro", "liquid", "pascal", "scala", "lua", "luau", "objc", "r", "solidity", "nix", "yaml", "twig", "xml", "properties", "cfml", "cfscript", "cfquery", "cobol", "vbnet", "erlang", "terraform", "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
+    /** 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[];
+    /**
+     * Normalized return/result type name for a function/method (the bare class
+     * name, smart-pointer pointee unwrapped). Captured for C/C++ so resolution
+     * can infer a chained receiver's type from what the inner call returns —
+     * `Foo::instance().bar()` resolves `bar` on `Foo` (issue #645). Undefined for
+     * languages/symbols where it isn't captured.
+     */
+    returnType?: 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'
+    /** 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[]
+    /** 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
+    /** 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
+    /** 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;
 }
+/**
+ * Kinds an unresolved reference can carry. `function_ref` is internal-only —
+ * a function name used as a VALUE (callback registration, #756). It never
+ * becomes an edge kind: resolution maps it to a `references` edge targeting
+ * function/method nodes only (see `matchFunctionRef`).
+ */
+export type ReferenceKind = EdgeKind | 'function_ref';
 /**
  * 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[]
+    /** ID of the node containing the reference */
+    fromNodeId: string;
+    /** Name being referenced */
+    referenceName: string;
+    /** Type of reference (call, type, import, etc.) */
+    referenceKind: ReferenceKind;
+    /** 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[]
+    /** 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
+    /** 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
+    /** 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[]
+    /** Matching node */
+    node: Node;
+    /**
+     * Relevance score for relative ranking only — higher is more relevant.
+     * NOT normalized and NOT a 0-1 fraction: the FTS path returns an unbounded
+     * BM25 magnitude (often in the tens or hundreds), while the fuzzy/exact
+     * paths return ~0-1. Use it to order results, not as an absolute percentage.
+     */
+    score: number;
+    /** Matched text snippets for highlighting */
+    highlights?: string[];
+}
+/**
+ * A symbol whose name-segments match prose words from a prompt — the
+ * graph-derived signal behind the front-load hook's medium tier
+ * (CodeGraph.getSegmentMatches). Always verified to exist in `nodes` at the
+ * time it is returned.
+ */
+export interface SegmentMatch {
+    /** Symbol name as indexed (e.g. `OrderStateMachine`). */
+    name: string;
+    /** Kind of the representative definition. */
+    kind: NodeKind;
+    /** File of the representative definition. */
+    filePath: string;
+    /** 1-based start line of the representative definition. */
+    startLine: number;
+    /** The prompt words (normalized) that matched this name's segments. */
+    matchedWords: 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[]
+    /** 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
+    /** 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
+    /** 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
+    /** 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
-    }
+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
+    /** 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
-  }
+    /** 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[]
+    /** 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
+//# sourceMappingURL=types.d.ts.map