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` | 関数、クラス、インターフェース、トレイト |
| 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

**Node kinds:** `function`（関数）, `method`（メソッド）, `class`（クラス）, `module`（モジュール）, `struct`（構造体）, `interface`（インターフェース）, `trait`（トレイト）, `enum`（列挙型）, `namespace`（名前空間）, `contract`（コントラクト）, `library`（ライブラリ）, `template`（テンプレート）, `proxy`（プロキシ）

**Node origins:** `source`（ソース）, `proxy`（プロキシ）, `binary`（バイナリ）, `synthetic`（合成）

**Edge kinds:** `calls`（呼び出し）, `inherits`（継承）, `implements`（実装）, `contains`（包含）, `imports`（インポート）, `resolves_to`（解決先）, `type_uses`（型使用）, `specializes`（特殊化）, `corresponds_to`（対応）

**Edge confidence:** `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()`、汚染伝播、特権境界の横断が動作するためのデータを提供します。検出は4つのレイヤーで実行され、後続のレイヤーが前のレイヤーを上書きします。

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"

参照は正確なノードIDまたは一意の名前/サフィックスである場合があります。あいまいな参照、不明な内部エンドポイント、無効なenum値、および不正なTOMLは`ValueError`を発生させます。`external = true`を設定すると、未解決のエンドポイントが明示的に許可され、プロキシノードが作成されます。このファイルは安定した公開構成インターフェースです。

### 分析の制限事項

- `entrypoint_paths_to()`はコールグラフの到達可能性を報告し、攻撃者が制御するデータフローは報告しません。事前分析のtaint結果を大まかな別個のシグナルとして使用してください。Trailmarkはまだ手続き間taint分析を実行しません。
- 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