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. 解析

一种特定语言的解析器遍历目录，将每个文件解析为 tree-sitter AST，并提取：

- **节点** — 函数、方法、类、结构体、接口、特性、枚举、模块、命名空间
- **边** — 调用、继承、实现、包含、导入
- **元数据** — 类型注解、圈复杂度、分支、文档字符串、异常类型

### 支持的语言

| 语言 | 扩展名 | 关键构造 |
| --- | --- | --- |
| Python | `.py` | 函数、类、方法 |
| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` | 函数、类、箭头函数 |
| TypeScript | `.ts`, `.tsx` | 函数、类、接口、枚举 |
| PHP | `.php` | 函数、类、接口、特性（traits） |
| Ruby | `.rb` | 方法、类、模块 |
| C | `.c`, `.h` | 函数、结构体、枚举 |
| C++ | `.cpp`, `.hpp`, `.cc`, `.hh`, `.cxx`, `.hxx` | 函数、类、结构体、命名空间 |
| C# | `.cs` | 方法、类、接口、结构体、枚举、命名空间 |
| Java | `.java` | 方法、类、接口、枚举 |
| Go | `.go` | 函数、方法、结构体、接口 |
| Rust | `.rs` | 函数、结构体、特性（traits）、枚举、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```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
# Example: single explicit entrypoint
[entrypoints.cli_main]
function = "my_package.cli:main"
trust = "high"
asset = "sensitive"

# Example: rule-based catch-all for Spring @RequestMapping
[[entrypoint_patterns]]
pattern = "^(org\\.example\\.).* (get|post|put|delete|patch)$"
trust = "medium"
asset = "api"
``````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"

引用可以是精确的节点ID或唯一的名称/后缀。歧义引用、未知内部端点、无效枚举值和格式错误的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