classDef src fill:#007bff26,stroke:#007bff,color:#007bff
classDef parse fill:#28a74526,stroke:#28a745,color:#28a745
classDef data fill:#6f42c126,stroke:#6f42c1,color:#6f42c1
classDef query fill:#ffc10726,stroke:#e6a817,color:#e6a817

class A src
class B parse
class C,D data
class E,F query

### 1. Парсинг

Языковой парсер обходит директорию, анализирует каждый файл в AST tree-sitter и извлекает:

- **Узлы** — функции, методы, классы, структуры, интерфейсы, трейты, перечисления, модули, пространства имён
- **Рёбра** — вызовы, наследование, реализация, включение, импорты
- **Метаданные** — аннотации типов, цикломатическая сложность, ветвления, строки документации, типы исключений

### Поддерживаемые языки

| Язык | Расширения | Ключевые конструкции |
| --- | --- | --- |
| Python | `.py` | функции, классы, методы |
| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` | функции, классы, стрелочные функции |
| TypeScript | `.ts`, `.tsx` | функции, классы, интерфейсы, перечисления |
| PHP | `.php` | функции, классы, интерфейсы, трейты |
| Ruby | `.rb` | методы, классы, модули |
| C | `.c`, `.h` | функции, структуры, перечисления |
| C++ | `.cpp`, `.hpp`, `.cc`, `.hh`, `.cxx`, `.hxx` | функции, классы, структуры, пространства имён |
| C# | `.cs` | методы, классы, интерфейсы, структуры, перечисления, пространства имён |
| Java | `.java` | методы, классы, интерфейсы, перечисления |
| Go | `.go` | функции, методы, структуры, интерфейсы |
| Rust | `.rs` | функции, структуры, трейты, перечисления, блоки impl |
| Solidity | `.sol` | контракты, интерфейсы, библиотеки, функции, модификаторы, структуры, перечисления |
| Cairo | `.cairo` | функции, трейты, структуры, перечисления, блоки impl, контракты StarkNet |
| Circom | `.circom` | шаблоны, функции, сигналы, компоненты |
| Haskell | `.hs` | функции, типы данных, классы типов, экземпляры |
| Erlang | `.erl` | функции, записи, поведения, модули |
| Miden Assembly | `.masm` | процедуры, точки входа, константы, вызовы |
| Swift | `.swift` | функции, классы, структуры, перечисления, протоколы, расширения |
| Objective-C | `.m`, `.mm`, `.h` | C-функции, классы, методы (именование на основе селекторов) |
| Kotlin | `.kt`, `.kts` | функции, классы, интерфейсы, классы данных, объекты, методы |
| Dart | `.dart` | функции, классы, абстрактные классы, методы, конструкторы |
| Move | `.move` | модули, функции, импорты, прямые вызовы |
| Tact | `.tact` | контракты, структуры, приёмники, функции |
| Func | `.fc`, `.func` | функции, включения, прямые вызовы |
| Sway | `.sw` | интерфейсы ABI, структуры, методы impl, функции |
| Rego | `.rego` | пакеты, импорты, правила политик, вызовы правил |
| Proto | `.proto` | сервисы, RPC, сообщения, поля, перечисления |
| Thrift | `.thrift` | сервисы, функции, структуры, поля, перечисления |
| GraphQL | `.graphql`, `.gql` | типы объектов, корневые операции, поля, перечисления |
| SQL | `.sql` | схемы, таблицы, представления, функции, процедуры |```mermaid
flowchart TD
    subgraph "Per-File Parsing"
        F["Source file"] --> TS["tree-sitter AST"]
        TS --> EX["Extract nodes"]
        TS --> EC["Extract call edges"]
        TS --> EB["Count branches"]
        TS --> ET["Resolve types"]
    end

    EX --> CG["CodeGraph"]
    EC --> CG
    EB --> CG
    ET --> CG

    classDef src fill:#007bff26,stroke:#007bff,color:#007bff
    classDef parse fill:#28a74526,stroke:#28a745,color:#28a745
    classDef extract fill:#ffc10726,stroke:#e6a817,color:#e6a817
    classDef data fill:#6f42c126,stroke:#6f42c1,color:#6f42c1

    class F src
    class TS parse
    class EX,EC,EB,ET extract
    class CG data

class CodeUnit {
    id: str
    name: str
    kind: NodeKind
    location: SourceLocation
    parameters: tuple[Parameter]
    return_type: TypeRef
    exception_types: tuple[TypeRef]
    cyclomatic_complexity: int
    branches: tuple[BranchInfo]
    docstring: str
}

class CodeEdge {
    source_id: str
    target_id: str
    kind: EdgeKind
    confidence: EdgeConfidence
}

class Annotation {
    kind: AnnotationKind
    description: str
    source: str
}

class EntrypointTag {
    kind: EntrypointKind
    trust_level: TrustLevel
    description: str
    asset_value: AssetValue
}

CodeGraph "1" *-- "*" CodeUnit
CodeGraph "1" *-- "*" CodeEdge
CodeGraph "1" *-- "*" Annotation
CodeGraph "1" *-- "*" EntrypointTag

**Типы узлов:** `function`, `method`, `class`, `module`, `struct`, `interface`, `trait`, `enum`, `namespace`, `contract`, `library`, `template`, `proxy`

**Источники узлов:** `source`, `proxy`, `binary`, `synthetic`

**Типы рёбер:** `calls`, `inherits`, `implements`, `contains`, `imports`, `resolves_to`, `type_uses`, `specializes`, `corresponds_to`

**Уверенность рёбер:** `certain`, `inferred`, `uncertain`

Неразрешённые вызовы материализуются в виде прокси-узлов, таких как
`proxy.unresolved:<raw-symbol>`, чтобы результаты обхода могли показать, где анализ исходного кода потерял разрешение, вместо того чтобы молча отбрасывать это ребро. Поддержка бинарного анализа импортирует внешние JSON-графы вызовов; Trailmark сам не дизассемблирует исполняемые файлы.

### Пример графа

Дан следующий код на Python:```python
class Auth:
    def verify(self, token: str) -> bool:
        return self._check_sig(token)

    def _check_sig(self, token: str) -> bool:
        ...

def handle_request(req: Request) -> Response:
    auth = Auth()
    if auth.verify(req.token):
        return process(req)
    return deny()

classDef fn fill:#007bff26,stroke:#007bff,color:#007bff
classDef cls fill:#6f42c126,stroke:#6f42c1,color:#6f42c1

class HR,P,D fn
class A,AV,CS cls

## Установка

В примерах ниже отслеживается текущая ветка разработки. Для последней
опубликованной версии установите из PyPI. Для точного набора функций, описанных
здесь, установите из копии репозитория и запускайте команды через `uv run`.```bash
# Latest published release
uv pip install trailmark

# Current checkout / development branch
uv sync --all-groups

### Обнаружение точек входа

Trailmark автоматически заполняет `graph.entrypoints`, чтобы `attack_surface()`, распространение меток и пересечение границ привилегий имели данные для работы. Обнаружение выполняется в четыре слоя, каждый из которых переопределяет предыдущий:

1. **Общая эвристика `main`.** Любая функция с именем `main` в любом языке. Помечается как `user_input` / `trusted_internal` / `low`.
2. **Сканирование с учётом фреймворка.** Шаблоны декораторов, атрибутов и видимости для каждого языка — см. таблицу ниже.
3. **`pyproject.toml [project.scripts]`.** Явные цели CLI получают повышенную оценку доверия и классификацию активов.
4. **Локальный файл переопределения в репозитории.** Точки входа, созданные вручную в `.trailmark/entrypoints.toml`, всегда имеют приоритет.

Покрытие фреймворков:

| Язык | Обнаруженные фреймворки |
| --- | --- |
| Python | Flask, FastAPI, aiohttp, Click, Typer, Celery |
| JavaScript / TypeScript | NestJS, Next.js (App Router + Pages API), AWS Lambda |
| Java | Spring MVC / WebFlux, JAX-RS, Kafka listeners, servlets |
| C# | ASP.NET Core, Azure Functions |
| PHP | Symfony `#[Route]` attributes + legacy annotations |
| Rust | actix-web, rocket, FFI exports (`#[no_mangle]`, `pub extern "C"`), async-main attributes |
| Solidity | `external` / `public` visibility |
| Cairo / StarkNet | `#[external]`, `#[view]`, `#[l1_handler]`, `#[constructor]` |
| Circom | `component main` declarations |
| Miden Assembly | `export.<name>` directives |
| Haskell | top-level `main ::` / `main =` |
| Erlang | functions listed in `-export([...])` |
| Swift | `@main` app attribute |
| Objective-C | `UIApplicationDelegate` lifecycle selectors (e.g. `application:openURL:options:`) |
| Kotlin | Spring MVC / WebFlux annotations (shared with Java), Android component lifecycle methods (`onCreate`, `onReceive`, `onBind`, ...) |
| Dart | `@pragma('vm:entry-point')` native-callable markers |
| Go | `http.HandleFunc` / `http.Handle` stdlib registrations, gin/chi/echo-style `<router>.GET/POST/...` handler registrations |
| Ruby | Rails controller actions (classes inheriting `ApplicationController` / `ActionController::*`), Sidekiq worker `perform` methods |
| C / C++ | `extern "C"` linkage, `__attribute__((visibility("default")))`, `__declspec(dllexport)` |

Для всего, что не удалось обнаружить эвристикам, объявляйте точки входа явно в файле `.trailmark/entrypoints.toml` в корне проекта. Файл поддерживает как одноузловые, так и основанные на правилах записи:```toml
# Single-node entry
[[entrypoint]]
node = "my_module:handle_request"  # node id, or "module.path:function"
kind = "api"                       # user_input | api | database | file_system | third_party
trust = "untrusted_external"       # untrusted_external | semi_trusted_external | trusted_internal
asset_value = "high"               # high | medium | low
description = "HTTP POST /auth"

# Rule: every PHP script under public_html/ is a web-exposed entrypoint.
[[entrypoint]]
file_glob = "public_html/**/*.php"
kind = "user_input"
trust = "untrusted_external"
asset_value = "high"
description = "Web-exposed PHP script"

# Rule: any function that takes a PSR-7 request object.
[[entrypoint]]
param_type = "ServerRequestInterface"
kind = "api"
trust = "untrusted_external"
asset_value = "high"
description = "PSR-7 HTTP handler"

# Rule: functions named `handle_*`.
[[entrypoint]]
name_regex = "^handle_"
kind = "api"
trust = "untrusted_external"

# Rule: conditions compose with AND — web.py files AND name starts with handle_.
[[entrypoint]]
file_glob = "public/*.py"
name_regex = "^handle_"
kind = "api"
trust = "untrusted_external"

Ссылки могут быть точными идентификаторами узлов или уникальными именами/суффиксами. Неоднозначные ссылки, неизвестные внутренние конечные точки, недопустимые значения перечислений и некорректный TOML вызывают `ValueError`. Установка `external = true` явно разрешает неопределённые конечные точки и создаёт прокси-узлы. Этот файл является стабильным общедоступным интерфейсом конфигурации.

### Ограничения анализа

- `entrypoint_paths_to()` сообщает о достижимости графа вызовов, а не о потоке данных, контролируемом атакующим. Используйте результаты предварительного анализа уязвимостей как грубый отдельный сигнал; Trailmark пока не выполняет межпроцедурный анализ распространения меток.
- TypeScript разрешает прямые вызовы и простые получатели, назначенные с помощью `new ConcreteClass()`. Диспетчеризация интерфейсов через манифесты, вычисляемые имена свойств, контейнеры внедрения зависимостей и другие динамические механизмы остаётся в режиме «наилучшего приближения».
- Поддержка SQL ориентирована на PostgreSQL и извлекает схемы, таблицы, представления, функции, процедуры и зависимости процедур/представлений. Это не полный валидатор диалекта SQL или анализатор семантики запросов.

### Программный API```python
from trailmark.parse import parse_directory, parse_file
from trailmark.query.api import QueryEngine

# Parse-only API: get the raw CodeGraph without building GraphStore/QueryEngine.
graph = parse_file("path/to/file.py")
graph = parse_directory("path/to/project", language="auto")

# Single-language (default) or auto-detect + merge across all languages
engine = QueryEngine.from_directory("path/to/project")
engine = QueryEngine.from_directory("path/to/project", language="auto")
engine = QueryEngine.from_directory("path/to/project", language="python,rust")

# Direct neighbors
engine.callers_of("handle_request")
engine.callees_of("handle_request")

# Transitive slicing — who could reach this sink, or what could it reach?
engine.ancestors_of("Auth._check_sig")
engine.reachable_from("handle_request")

# Attack-surface paths from any detected entrypoint
engine.entrypoint_paths_to("Auth._check_sig")

# All call paths between two nodes
engine.paths_between("handle_request", "Auth._check_sig")

# Functions with cyclomatic complexity >= 10
engine.complexity_hotspots(10)

# What functions can raise a given exception? (uses parser-detected
# exception_types; no runtime tracing required)
engine.functions_that_raise("PermissionError")

# Add and query semantic annotations
from trailmark.models.annotations import AnnotationKind

engine.annotate(
    "handle_request",
    AnnotationKind.ASSUMPTION,
    "Caller has already authenticated the session token",
    source="llm",
)
engine.annotations_of("handle_request")
engine.nodes_with_annotation(AnnotationKind.FINDING)

# Diff against an earlier snapshot of the same codebase
before = QueryEngine.from_directory("before/")
diff = engine.diff_against(before)
# diff contains: summary_delta, nodes {added/removed/modified},
# edges {added/removed}, entrypoints {added/removed/modified}

# Run the built-in audit-oriented preanalysis passes
engine.preanalysis()
engine.findings()
engine.subgraph_names()

# Programmatic augmentation hooks for external tooling
engine.augment_sarif("results.sarif")
engine.augment_weaudit("findings.json")

## Лицензия

Apache-2.0