cartog-core 0.11.3

Core types and utilities for cartog code graph indexer
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

# cartog-core

Core types and utilities for the cartog code graph indexer.

## Overview

Foundation crate with zero internal dependencies. Defines the shared data model used by all other cartog crates: symbols, edges, and their metadata. Also provides pure utility functions like language detection.

## How it works

### Stable symbol IDs

Every symbol gets a deterministic ID built from its location in the code structure, not its position in the file:

```
file_path:kind:qualified_name
```

The qualified name encodes the parent chain with `.` separators:

- Top-level function: `src/auth.py:function:validate`
- Method in class: `src/auth.py:method:TokenService.validate`
- Nested class: `src/auth.py:class:Outer.Inner`

This ID is **invariant to line movements** within a file — renaming or moving lines won't change it, only renaming the symbol or its parent chain will.

### Builder pattern

`Symbol::new()` returns a symbol with sensible defaults (`Public` visibility, not async, no docstring). Builder-style setters (`with_parent`, `with_signature`, `with_visibility`, `with_async`, `with_docstring`) allow incremental customization without a 15-argument constructor.

### Language detection

`detect_language()` maps file extensions to language names (e.g., `.py` → `"python"`, `.tsx` → `"tsx"`, `.md` → `"markdown"`). It's a pure function with no tree-sitter dependency, which allows lightweight crates like `cartog-watch` and `cartog-lsp` to filter files without pulling in grammar crates.

## Public API

| Export | Description |
|--------|-------------|
| `Symbol` | Code symbol with stable ID, kind, location, signature, visibility |
| `SymbolKind` | Function, Class, Method, Variable, Import, Interface, Enum, TypeAlias, Trait, Module, Document |
| `Edge` | Relationship between symbols (source → target) |
| `EdgeKind` | Calls, Imports, Inherits, References, Raises, Implements, TypeOf |
| `Visibility` | Public, Private, Protected |
| `FileInfo` | Indexed file metadata (path, hash, language, symbol count) |
| `ChangesResult` | Result of a git-changes query |
| `symbol_id()` | Build a stable symbol ID from components |
| `detect_language()` | Map file extension to language name |

## Crate dependencies

None (this is the root of the dependency graph).